Guida passo passo per principianti
Cosa ti serve
- Un account FlipSight.
- Una foto del bot: un file GIF, JPG o PNG di massimo 5 MB, largo e alto almeno 175 px.
- Il tuo computer su cui eseguire il bot Le mosse del tuo bot vengono calcolate sul computer su cui gira il connettore. Anche con lo stesso motore la forza può cambiare in base alla potenza del computer e alle impostazioni del motore, e se cambi computer o impostazioni il punteggio può muoversi di conseguenza.
- Python 3, un programma gratuito che esegue il connettore. Funziona dalla versione 3.9 in poi; si consiglia la 3.11 o successiva. Lo controlli al passo 5.
- Il motore del tuo bot. Il connettore include un motore di pratica per i test.
1. Registra il tuo bot
Accedi e apri la pagina dei bot (othelloclub.com/it/flipsight/lab). Nel riquadro Registra il mio bot in alto, inserisci un nome in Nome del bot (2–24 caratteri). In Giochi supportati lascia per ora selezionato solo Standard. Scegli un'immagine in Carica foto del bot, poi premi il pulsante Registra il mio bot.
Risultato atteso: compare il riquadro Token di connessione (visibile una sola volta) con un lungo testo che inizia con fsbm_.
2. Conserva il token
Questo lungo testo è il token, una password solo per il tuo bot. Il connettore lo usa per dimostrare al server che agisce per questo bot. Copialo tutto e incollalo temporaneamente da qualche parte, per esempio in un editor di testo. Una volta chiuso il riquadro, non potrai più vedere lo stesso token.
Tratta il token come una password. Non mostrarlo a nessuno e non pubblicarne screenshot. Se lo perdi o qualcuno l'ha visto, apri Gestisci nell'elenco dei bot e premi Genera token di connessione. Quando ottieni un nuovo token, quello vecchio smette subito di funzionare.
3. Scarica il connettore
Premi Scarica esempi Python per scaricare il file ZIP ed estrailo. Questa guida chiama la cartella estratta «cartella del bot». Mettila in un posto facile da trovare, come la scrivania.
Risultato atteso: la cartella del bot contiene il file README.md e la cartella tools.
4. Apri un terminale nella cartella del bot
Un terminale è una finestra in cui si scrivono comandi. Aprilo come segue in base al tuo sistema.
macOS: premi Command+Space, digita Terminale e aprilo. Digita cd e uno spazio, trascina la cartella del bot nella finestra, poi premi Invio.
Linux: nel gestore di file, fai clic destro sulla cartella del bot e scegli «Apri nel terminale». Il nome del menu può cambiare tra le distribuzioni. Se il menu non c'è, apri un terminale e usa cd come su macOS.
Windows: apri la cartella del bot in Esplora file. Digita powershell nella barra degli indirizzi in alto e premi Invio. Si apre una finestra di PowerShell in quella cartella.
Verifica: digita il comando qui sotto e premi Invio. Funziona se README.md e tools compaiono nell'elenco. Questo comando è lo stesso su macOS, Linux e Windows PowerShell.
ls5. Controlla Python
Nella stessa finestra, copia il comando per il tuo sistema, incollalo e premi Invio. Puoi usare il pulsante di copia in alto a destra di ogni riquadro di codice.
macOS / Linux
python3 --versionWindows PowerShell
py --versionRisultato atteso: una versione che inizia con 3, come Python 3.11.9. Funziona dalla versione 3.9 in poi. Se il comando non viene trovato, installa Python come indicato sotto, chiudi la finestra e ricomincia dal passo 4.
macOS: scarica il programma di installazione per macOS (.pkg) da python.org e installalo. Poi esegui una volta Install Certificates.command dalla cartella di Python in Applicazioni. Così si preparano i certificati necessari per le connessioni sicure (HTTPS).
Linux: installa python3 con il gestore software o il gestore di pacchetti della tua distribuzione.
Windows: installa il Python install manager da python.org.
6. Inserisci il token
Metti il token in una variabile d'ambiente, un'impostazione temporanea che esiste solo in questa finestra del terminale. Il suo nome è FS_BOT_TOKEN. Copia qui sotto il comando di una riga per il tuo sistema, incollalo e premi Invio una volta. Compare quindi Bot token, in attesa del tuo inserimento. Ora incolla il token copiato al passo 2 e premi Invio.
macOS / Linux
printf 'Bot token: '; read -r -s FS_BOT_TOKEN; printf '\n'; export FS_BOT_TOKENWindows PowerShell
$env:FS_BOT_TOKEN = [Net.NetworkCredential]::new('', (Read-Host 'Bot token' -AsSecureString)).PasswordSu macOS e Linux il token incollato non viene mostrato, e su Windows vedi * al posto dei suoi caratteri. In entrambi i casi è normale. Poiché il token non è scritto nel comando, non resta nella cronologia dei comandi. L'impostazione vale solo in questa finestra. Se l'hai chiusa o hai aperto una nuova finestra, ripeti i passi 4 e 6.
In PowerShell incolla il token con Ctrl+V.
Risultato atteso: il prompt per il comando successivo ricompare senza errori.
7. Avvia il connettore
Nella stessa finestra, copia il comando qui sotto così com'è, incollalo e premi Invio. Non cambiare i nomi dei file che contiene. Il tuo bot si collega con il motore di prova, un motore molto debole che gioca la casella legale con il numero più basso.
macOS / Linux
python3 tools/bot_match_client.py --engine-threads 1 --engine 'python3 tools/bot_match_example_engine.py'Windows PowerShell
py tools/bot_match_client.py --engine-threads 1 --engine 'py tools/bot_match_example_engine.py'È normale che il comando non mostri testo e non restituisca il prompt durante l’esecuzione. Per mantenere il bot online, lascia questa finestra aperta con il connettore e il motore in esecuzione e impedisci al computer di andare in sospensione. Chiudendo questa finestra o premendo Ctrl+C, entrambi i programmi si arrestano e il bot va offline. Esegui di nuovo il comando sopra per riportarlo online. Il connettore accetta automaticamente le richieste degli altri bot.
Finché il bot gira con il motore di prova non riceve incontri automatici, e i suoi incontri contro altri bot, anche quelli che chiedi tu, non sono classificati. Riavvialo con il tuo motore (passo 10) e da quel momento viene abbinato e classificato.
Risultato atteso: nell'elenco Bot registrati della pagina dei bot, il pallino a destra del nome del tuo bot è verde. Passandoci sopra con il mouse compare Online.
8. Prova con una prima partita
Nella pagina dei bot, scegli il tuo bot in Il mio bot giocatore. Scegli un bot qualsiasi nell'elenco Bot FlipSight, premi Sfida e conferma nella finestra che si apre. In tutti i tipi di gioco il server calcola le mosse dei bot FlipSight, quindi non serve tenere aperta la stanza di gioco.
Risultato atteso: la stanza di gioco mostra due scacchiere e a ogni turno del tuo bot viene posata una pedina. Il motore di prova è molto debole, quindi perdere è normale.
9. Lascialo attivo dopo aver chiuso la finestra (facoltativo)
Dopo la prima partita, ferma il connettore con Ctrl+C nella finestra del passo 7. Riavvialo lì con il comando qui sotto. Mantieni il computer attivo.
macOS / Linux
Usa screen e sostituisci mybot con un nome diverso per ogni bot. Dopo l’avvio premi Ctrl+A e poi D per poter chiudere la finestra. Per fermare il bot, torna alla sessione con il comando in basso e premi Ctrl+C.
Avvia
screen -S mybot python3 tools/bot_match_client.py --engine-threads 1 --engine 'python3 tools/bot_match_example_engine.py'Ferma
screen -r mybotWindows PowerShell
Windows: nella barra delle applicazioni compare una finestra ridotta a icona in cui gira il bot. Puoi chiudere la finestra di PowerShell attuale. Per fermarlo, apri la finestra ridotta a icona e premi Ctrl+C, oppure chiudi quella finestra.
Avvia
Start-Process py -ArgumentList 'tools/bot_match_client.py --engine-threads 1 --engine "py tools/bot_match_example_engine.py"' -WorkingDirectory $PWD -WindowStyle Minimized10. Passa al tuo motore
Dopo la prova di connessione, passate al vostro motore: opzioni dedicate sotto per Edax o Egaroucid, --nboard per altri motori compatibili, JSON per un motore proprio. Il token resta lo stesso.
- Edax: --edax
- Egaroucid: --egaroucid
- Motori NBoard come NTest: --nboard
- Motore fatto da te: collegarlo tramite JSON
Seleziona una variante (Anti, 10x10, Octagon, Reversi classico) in Giochi supportati solo se il tuo motore ne conosce le regole. Altri bot e persone possono sfidare il tuo bot in ogni gioco selezionato. Per cambiarlo, apri Gestisci nell'elenco dei bot, modifica Giochi supportati e premi Salva. Non puoi cambiarlo mentre una partita è in corso o una sfida è in attesa.
Problemi comuni
| Sintomo | Causa e soluzione |
|---|---|
| Il bot mostra un pallino grigio (offline). | Controlla che la finestra del connettore sia ancora in esecuzione. Si ferma se chiudi la finestra, premi Ctrl+C o il computer va in stop. |
Dice che il comando non è stato trovato.command not found / is not recognized | Python manca, oppure la finestra non è stata riaperta dopo l'installazione. Vedi il passo 5, apri una nuova finestra e ricomincia dal passo 4. |
Dice che il file non si può aprire.can't open file | L'hai eseguito fuori dalla cartella del bot. Spostati nella cartella del bot come al passo 4 e controlla con ls che README.md e tools siano elencati. |
Dice che il token manca e si chiude.FS_BOT_TOKEN is missing or invalid | Questa finestra non ha il token. Se hai aperto una nuova finestra, ripeti il passo 6. |
Dice che il token è stato rifiutato e si ferma.Bot credential rejected | Il token è stato incollato male o è vecchio. Dopo aver generato un nuovo token o disattivato il bot, il vecchio token non funziona più. Ricomincia dal passo 6 con il token più recente. |
La stessa riga di errore continua a comparire.Connection/state error | Controlla la connessione a internet. Su macOS, controlla di aver eseguito Install Certificates.command al passo 5. Se compare solo durante le partite, il server potrebbe rifiutare la mossa del tuo motore perché illegale. Il connettore invia di nuovo la stessa mossa, quindi bisogna correggere il motore. |
| Il pulsante di sfida non funziona, o la sfida non viene accettata. | Seleziona Il mio bot giocatore e verifica che entrambi i bot siano online. L’avversario deve accettare sfide dirette e avere un posto libero. Una sfida senza risposta scade dopo 120 secondi. |
Il bot non fa nessuna mossa e poi perde per tempo, oppure la partita viene annullata.Engine failed for match | Il motore non ha risposto in tempo o la sua risposta aveva un formato sbagliato. Controlla il comando del motore e la sua uscita JSON su una riga. Se un bot non fa la prima mossa entro 30 secondi dall'inizio, la partita viene annullata. |
| Non arrivano sfide nelle varianti. | La finestra di sfida elenca solo i giochi supportati da entrambi i bot. Controlla che il gioco sia selezionato in Giochi supportati del tuo bot e che anche l'altro bot lo supporti. Un bot collegato tramite --edax o --nboard dovrebbe avere selezionato solo Standard. |
Glossario
| Termine | Significato |
|---|---|
| API | Un modo concordato con cui i programmi si scambiano richieste e risposte. Se ne occupa il connettore per te. |
| Token | Una password solo per il tuo bot. Il connettore la usa per dimostrare al server di quale bot si tratta. |
| Terminale | Una finestra in cui si scrivono comandi. Su Windows usa PowerShell. |
| Variabile d'ambiente | Un'impostazione temporanea passata ai programmi avviati da una finestra del terminale. Scompare quando la finestra viene chiusa. |
| JSON | Un formato per scrivere dati come testo. Esempio: {"move":19} |
| Motore | Un programma che esamina una posizione e sceglie una mossa. |
| Adattatore | Un piccolo programma che converte i dati tra il tuo motore e il connettore. |
| NBoard | Un formato aperto con cui i motori di Othello e i programmi di scacchiera si scambiano posizioni e mosse. I motori che lo supportano, come NTest, si collegano senza adattatore. |
| Mossa legale | Una casella in cui puoi giocare adesso. Il server le elenca in legal_moves. |
Collegare il tuo motore
Usa al massimo 4 thread per motore. Un incontro tra bot comprende due partite simultanee, con un massimo di 8 thread in totale.
Edax: --edax
Gli esempi di installazione e avvio qui sotto usano Edax 4.6 ed Egaroucid for Console 7.8.2.
Edax 4.6 non è incluso nel connettore. Scarica il file per il tuo sistema da Assets su Edax 4.6, mettilo nella cartella del bot ed estrailo con i comandi di preparazione sotto. I comandi Windows e Linux sono per computer x86-64.
Windows PowerShell (x86-64): edax-4.6-MS-windows-x86.zip
Prepara (solo la prima volta)
Expand-Archive -LiteralPath edax-4.6-MS-windows-x86.zip -DestinationPath edax-4.6Avvia
py tools/bot_match_client.py --engine-threads 2 --edax "edax-4.6\wEdax-x86-64.exe"Linux (x86-64): edax-4.6-linux-x86.tar.gz
Prepara (solo la prima volta)
mkdir -p edax-4.6
tar -xzf edax-4.6-linux-x86.tar.gz -C edax-4.6
chmod +x edax-4.6/lEdax-x86-64Avvia
python3 tools/bot_match_client.py --engine-threads 2 --edax "edax-4.6/lEdax-x86-64"macOS: edax-reversi-4.6.tar.gz
Non esiste un eseguibile macOS ufficiale di Edax 4.6. Scarica Source code (tar.gz) ed edax-4.6-linux-x86.tar.gz dalla stessa versione. Compila l’eseguibile Mac dal sorgente; dall’archivio Linux viene estratto solo il file di valutazione condiviso data/eval.dat. Servono gli strumenti da riga di comando Xcode. I comandi di preparazione compilano il sorgente.
Prepara (solo la prima volta)
xcode-select --installtar -xzf edax-reversi-4.6.tar.gz
mv edax-reversi-4.6 edax-4.6
mkdir -p edax-4.6/bin
tar -xzf edax-4.6-linux-x86.tar.gz -C edax-4.6 data/eval.dat
(cd edax-4.6/src && make build ARCH=native OS=osx)Avvia
python3 tools/bot_match_client.py --engine-threads 2 --edax "edax-4.6/bin/mEdax-native"Edax può collegarsi anche indicando solo il percorso dell’eseguibile con --edax. Non serve un adattatore. Il connettore avvia Edax tramite xboard e invia entrambi i tempi rimasti prima di ogni mossa; Edax decide da sé il tempo di riflessione in base al proprio orologio (connettore v1.4.8 o successivo). Durante la partita Edax mantiene la propria partita e la tabella hash, e con --engine-ponder on cerca anche durante il tempo dell’avversario. --edax-protocol nboard mantiene la vecchia connessione NBoard.
Sostituite il percorso nel comando con quello completo del vostro eseguibile. Racchiudete tra virgolette doppie i percorsi con spazi. Se il file di valutazione non viene trovato, indicate eval.dat con --edax-eval.
Una connessione con --edax o --nboard gioca solo partite standard 8×8. Per questo bot lascia selezionato solo Standard in Giochi supportati. Se arriva una variante, il connettore non interpella il motore, nessuna mossa viene giocata e la partita viene annullata o persa per tempo.
Egaroucid: --egaroucid
Preparate Egaroucid for Console. Scegliete l’eseguibile console e mantenete resources al suo posto. Su macOS e Linux, usate un eseguibile compilato seguendo le istruzioni ufficiali. Il connettore invia posizione e tempo rimasto con setboard, settime e go, senza adattatore.
Windows PowerShell
py tools/bot_match_client.py --engine-threads 2 --egaroucid "egaroucid\Egaroucid_for_console.exe"macOS / Linux
python3 tools/bot_match_client.py --engine-threads 2 --egaroucid "egaroucid/bin/Egaroucid_for_Console.out"Entrambe le modalità supportano solo il gioco standard 8×8, con un motore per ogni partita simultanea. --max-think-seconds è il limite di sicurezza per mossa (10 secondi predefiniti). Se Egaroucid lo raggiunge, la ricerca viene fermata, viene giocata una mossa legale di riserva e il motore riparte al turno seguente.
Motori NBoard come NTest: --nboard
NBoard è un’applicazione grafica di Othello utilizzabile con NTest. Il protocollo NBoard è il suo formato pubblico di comunicazione con i motori; collega con --nboard i motori che lo supportano, come NTest. Resta aperto un motore per partita. Anche Edax lo supporta, ma collega Edax con --edax più sopra.
Windows PowerShell
py tools/bot_match_client.py --engine-threads 2 --nboard "path\to\engine.exe"macOS / Linux
python3 tools/bot_match_client.py --engine-threads 2 --nboard "path/to/engine"Una connessione con --edax o --nboard gioca solo partite standard 8×8. Per questo bot lascia selezionato solo Standard in Giochi supportati. Se arriva una variante, il connettore non interpella il motore, nessuna mossa viene giocata e la partita viene annullata o persa per tempo.
Motore fatto da te: collegarlo tramite JSON
Leggi questa parte solo se vuoi collegare un motore scritto da te. Se usi Edax, Egaroucid o un motore NBoard, hai già finito più sopra e puoi saltarla.
Ogni volta che tocca al tuo bot, il connettore esegue my_adapter.py una volta. Gli passa la posizione attuale in una riga (dove sono le pedine, a chi tocca, quali caselle sono legali, quanto tempo resta), my_adapter.py risponde con una casella in una riga e il connettore gioca quella mossa sul server. my_adapter.py è un piccolo file Python che sta nel mezzo e chiede la mossa al tuo motore. Il connettore si occupa della connessione al server, del token e dell'invio delle mosse, quindi questo file non deve mai pensarci.
bot_match_client.py→ my_adapter.pybot_match_client.py← my_adapter.pyDi che tipo è il tuo motore?
- Un motore che sceglie la mossa con codice Python: usa l'esempio A qui sotto.
- Un file di programma che a ogni avvio stampa una riga di risposta e si chiude: usa l'esempio B qui sotto.
- Un eseguibile che resta aperto e scambia comandi di continuo: se supporta NBoard, collegalo con --nboard qui sopra. Con un altro protocollo, adatta l'esempio B a quel protocollo e fai in modo che my_adapter.py tenga aperto il motore e scambi una riga alla volta in un ciclo.
Passo 1: un file che controlla solo la connessione (my_adapter.py)
Nella cartella del bot (dove si trovano README.md e tools) crea un file chiamato my_adapter.py, incolla il codice qui sotto così com'è e salvalo. Questo file non usa nessun motore e risponde semplicemente con la prima casella legale. Serve a verificare che la connessione funzioni prima di collegare il tuo motore.
import json
import sys
def choose_move(position):
legal = position["legal_moves"]
return legal[0] if legal else -1
line = sys.stdin.readline()
position = json.loads(line)
move = choose_move(position)
print(json.dumps({"move": move}), flush=True)
Controllare ingresso e uscita prima di collegare
Il comando del riquadro 1 passa la posizione di esempio direttamente all'adattatore. Dovrebbe stampare una riga: {"move": 19}. Quando vedi questa riga, usa il comando del riquadro 2 per avviare il connettore con questo adattatore, nella finestra che contiene il token del passo 6. Esegui i due riquadri separatamente. Se il tuo motore legge da solo questo formato JSON, puoi mettere il suo comando direttamente dopo --engine.
1. Prova solo l'adattatore
macOS / Linux
printf '%s\n' '{"board":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,2,1,0,0,0,0,0,0,1,2,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"color":1,"legal_moves":[19,26,37,44],"game_mode":"std","board_size":8,"blocked_squares":[],"placed":{"1":0,"2":0},"remaining_ms":60000,"match_id":123,"leg":0,"revision":0,"history":[],"round_no":null,"room_created_at":null,"budget_ms":10000}' | python3 my_adapter.pyWindows PowerShell
'{"board":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,2,1,0,0,0,0,0,0,1,2,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"color":1,"legal_moves":[19,26,37,44],"game_mode":"std","board_size":8,"blocked_squares":[],"placed":{"1":0,"2":0},"remaining_ms":60000,"match_id":123,"leg":0,"revision":0,"history":[],"round_no":null,"room_created_at":null,"budget_ms":10000}' | py my_adapter.py2. Avvia il connettore con l'adattatore
macOS / Linux
python3 tools/bot_match_client.py --engine-threads 2 --engine 'python3 my_adapter.py'Windows PowerShell
py tools/bot_match_client.py --engine-threads 2 --engine 'py my_adapter.py'Passo 2: passare a un file che chiama il tuo motore
Quando il passo 1 funziona, sostituisci tutto il contenuto di my_adapter.py con l'esempio A o B qui sotto. Cambia solo le righe contrassegnate con EDIT e lascia il resto com'è. Poi esegui di nuovo il comando di prova 1 qui sopra e controlla che compaia una riga di risposta. La mossa l'ha scelta il tuo motore, quindi è normale che esca una casella diversa da 19.
Esempio A: un motore che sceglie la mossa con una funzione Python
Questo esempio presume un file chiamato my_engine.py con una funzione search che sceglie la mossa. In EDIT 1 cambia il nome del file e quello della funzione, e in EDIT 2 cambia i valori passati, in modo che corrispondano al tuo motore. La funzione deve restituire il numero della casella (da 0 a 63) oppure una coordinata come d3.
import json
import sys
from pathlib import Path
from my_engine import search # EDIT 1: your engine file and function name
def think_ms(position):
# Time for this move: share the remaining clock over my remaining moves.
my_moves_left = position["board"].count(0) // 2 + 1
share = position["remaining_ms"] / my_moves_left
return int(min(share, position["budget_ms"]) * 0.8)
def choose_move(position):
if not position["legal_moves"]:
return -1
# EDIT 2: pass what your function needs
return search(
board=position["board"],
color=position["color"],
legal_moves=position["legal_moves"],
time_limit_ms=think_ms(position),
)
position = json.loads(sys.stdin.readline())
legal = position["legal_moves"]
try:
move = choose_move(position)
except Exception as error:
# The engine failed: note why in my_adapter.log and play the first legal square.
with open(Path(__file__).with_name("my_adapter.log"), "a") as log:
log.write(repr(error) + "\n")
move = legal[0] if legal else -1
print(json.dumps({"move": move}), flush=True)Esempio B: un motore che è un file di programma
Questo esempio presume che il programma legga una riga con 64 caratteri della scacchiera, il colore che deve muovere e il tempo di riflessione in millisecondi, e che risponda con una riga con una coordinata come D3 (. = vuota, X = nero, O = bianco). Ogni motore ha il suo formato, quindi cambia il nome del file di programma in EDIT 1, la riga inviata al motore in EDIT 2 e la parte che legge la risposta in EDIT 3 in modo che corrispondano al tuo motore.
my_adapter.py → my_engine
...........................OX......XO........................... X 1777my_engine → my_adapter.py
D3import json
import subprocess
import sys
from pathlib import Path
# EDIT 1: your engine program file (kept in the same folder as my_adapter.py)
ENGINE = Path(__file__).with_name("my_engine.exe" if sys.platform == "win32" else "my_engine")
def think_ms(position):
# Time for this move: share the remaining clock over my remaining moves.
my_moves_left = position["board"].count(0) // 2 + 1
share = position["remaining_ms"] / my_moves_left
return int(min(share, position["budget_ms"]) * 0.8)
def choose_move(position):
if not position["legal_moves"]:
return -1
# EDIT 2: build the line your engine reads
board = "".join(".XO"[cell] for cell in position["board"])
color = "X" if position["color"] == 1 else "O"
reply = subprocess.run(
[str(ENGINE)],
input=f"{board} {color} {think_ms(position)}\n",
text=True,
capture_output=True,
check=True,
timeout=position["budget_ms"] / 1000 * 0.9,
)
# EDIT 3: take the square out of your engine's answer
return reply.stdout.strip()
position = json.loads(sys.stdin.readline())
legal = position["legal_moves"]
try:
move = choose_move(position)
except Exception as error:
# The engine failed: note why in my_adapter.log and play the first legal square.
with open(Path(__file__).with_name("my_adapter.log"), "a") as log:
log.write(repr(error) + "\n")
move = legal[0] if legal else -1
print(json.dumps({"move": move}), flush=True)Tempo di riflessione: nelle partite tra bot ogni bot ha 1 minuto per partita, quindi pensare a lungo su una sola mossa fa perdere presto per tempo. Negli esempi, think_ms divide il tempo rimasto (remaining_ms) per le mosse che ti restano e decide così il tempo per questa mossa. budget_ms non è il tempo da spendere per questa mossa. È il tempo massimo per cui il connettore aspetta la risposta (10 secondi come impostazione predefinita). Se la risposta arriva più tardi, il bot non può continuare quella partita e la perde per tempo, quindi passa al tuo motore think_ms e non budget_ms.
Quando qualcosa non va: se la chiamata al motore fallisce, i file di esempio scrivono il motivo in my_adapter.log e giocano al suo posto la prima casella legale. Se le mosse ti sembrano strane, apri prima di tutto quel file. Il connettore non mostra sullo schermo i messaggi di errore dell'adattatore. Usa print solo per la riga di risposta e scrivi su un file qualsiasi testo di debug.
Velocità: il connettore tiene aperto my_adapter.py per ogni partita e invia una riga per mossa. Un file che risponde una riga e termina, come gli esempi, viene riavviato alla mossa successiva, quindi anche il tuo motore si riavvia ogni volta. Se il motore è lento ad avviarsi o deve conservare il lavoro delle mosse precedenti, trasforma my_adapter.py in un ciclo: leggi una riga, rispondi una riga, ripeti. Non leggere l'input fino alla fine e fai flush dopo ogni risposta.
Il resto di questa parte è materiale di riferimento su ciò che il connettore e my_adapter.py si scambiano. Se usi i file di esempio qui sopra così come sono, non hai bisogno di leggerlo.
JSON in ingresso (connettore → adattatore)
Questi sono dati di esempio inviati dal connettore, non codice eseguibile. Non salvarli come file Python. Durante la partita, il connettore invia automaticamente i dati aggiornati a ogni turno.
Qui sotto trovi un esempio con la posizione iniziale standard 8×8. Nelle partite reali il connettore inserisce la posizione attuale. board elenca le caselle da a1 verso destra, poi la riga successiva; 0=vuota, 1=nero, 2=bianco. color=1 chiede una mossa del nero. legal_moves elenca le caselle in cui puoi giocare. remaining_ms è il tempo rimasto sull'orologio della partita e budget_ms il tempo massimo per cui il connettore aspetta la risposta a questa mossa, entrambi in millisecondi (1000 = 1 secondo). Campi ed esempi per le varianti sono più in basso, nella sezione sulle varianti.
{"board":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,2,1,0,0,0,0,0,0,1,2,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"color":1,"legal_moves":[19,26,37,44],"game_mode":"std","board_size":8,"blocked_squares":[],"placed":{"1":0,"2":0},"remaining_ms":60000,"match_id":123,"leg":0,"revision":0,"history":[],"round_no":null,"room_created_at":null,"budget_ms":10000}JSON di risposta (adattatore → connettore)
Scrivi una delle risposte qui sotto come un'unica riga JSON che termina con un a capo. move è un numero di casella o una coordinata, senza distinzione tra maiuscole e minuscole. Su 8×8, d3 è (3−1)×8+3 = 19. Scegli sempre tra le legal_moves ricevute. Nelle coppie di bot, se non hai mosse legali, invia -1 o pass; nelle partite contro persone il server risolve i passi forzati. Scrivi su stdout solo la riga di risposta, senza altri messaggi.
{"move":19}{"move":"d3"}{"move":-1}Facoltativo: aggiungi environment alla risposta per segnalare i thread reali, la dimensione hash in MB e il ponder del motore (connettore v1.4.6 o successivo). Il connettore accetta solo numeri nell’intervallo e true/false e li mostra nelle informazioni del bot. Se il tuo adattatore aggiunge eval, il connettore la invia con la mossa negli incontri tra bot (per esempio {"move":19,"eval":1.5}). eval è la tua valutazione dopo la mossa, in pedine dal tuo lato e al massimo le caselle giocabili; --edax, --egaroucid e i motori NBoard la inviano da soli dopo l’aggiornamento a v1.5.3.
{"move":19,"environment":{"engine_threads":1,"hash_mb":32,"ponder":false}}Download
GitHub: flipsight-othello-bot-connector
.zip contiene guida, connettore e motore di esempio; .json è la specifica API e .md è la guida.
Implementare l'API da soli
Ferma prima il connettore di prova. Apri il flusso con il token del passo 6. Mantieni una connessione per token. Ogni riga contiene un evento JSON.
Flusso di eventi
curl -N 'https://othelloclub.com/flipsight_api/bot-stream' \
-H "Authorization: Bearer $FS_BOT_TOKEN"
Windows PowerShell
curl.exe -N https://othelloclub.com/flipsight_api/bot-stream -H "Authorization: Bearer $env:FS_BOT_TOKEN"Dopo hello arriva state. L’esempio mostra i campi utili per il tuo bot, il numero 2.
{
"type": "state",
"view": "agent",
"bot": {
"id": 2
},
"matches": [
{
"id": 123,
"status": "running",
"bot_a": 1,
"bot_b": 2,
"state": {
"legs": [
{
"turn": 1,
"black_participant": 0,
"revision": 1,
"status": "active",
"legal_moves": [2, 3, 12, 25, 42, 44, 45]
},
{
"turn": 1,
"black_participant": 1,
"revision": 0,
"status": "active",
"legal_moves": [2, 3, 12, 25, 42, 44, 45]
}
]
}
}
]
}Sul secondo tavoliere (leg 1) il tuo bot gioca con il nero (1). Quando turn vale 1, scegli una mossa da legal_moves e inviala con la revision di quel tavoliere. Per giocare, imposta il token in un secondo terminale come al passo 6 e usa i dati della partita in corso.
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_move","match_id":123,"leg":1,"revision":0,"move":2,"eval":1.5}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_move","match_id":123,"leg":1,"revision":0,"move":2,"eval":1.5}'Flusso di eventi
| Tipo | Descrizione |
|---|---|
hello | Connessione confermata. bot_id identifica il tuo bot. |
state | Sostituisci l’elenco di partite in corso e inviti. Se sei bot_b, puoi accettare un invito pending con agent_accept. |
match | Aggiorna la partita con questo id. Controlla su ogni tavoliere attivo se tocca al tuo bot. |
ping | Segnale di connessione ogni 10 secondi. Non occorre rispondere. |
closing | Ultima riga prima che il server chiuda il flusso. Se reason è overflow (troppe righe non inviate) o server_shutdown, riconnettiti e aggiornati con state. replaced significa che lo stesso token è in uso anche altrove. Non riconnetterti subito: attendi almeno 30 secondi, e di più se si ripete. Usa ogni token in un solo posto. |
Oggetto incontro (matches[])
| Campo | Tipo | Descrizione |
|---|---|---|
id | integer | ID dell’incontro (negativo nelle partite contro una persona) |
kind | string | human nelle partite contro una persona |
bot_a | integer | ID bot del partecipante 0 (0 per una persona) |
bot_b | integer | ID bot del partecipante 1 (0 per una persona) |
game_mode | string | Gioco (std, anti, grand, octagon, reversi) |
time_limit_sec | integer | Secondi per partita e per colore |
status | string | pending, running, finished, aborted, rejected, expired |
expires_ms | integer | Scadenza per l’accettazione (millisecondi) |
ranked | boolean | Se l’incontro è classificato |
state.status | string | active, finished o aborted |
state.game_mode | string | Gioco (std, anti, grand, octagon, reversi) |
state.board_size | integer 8 | 10 | Caselle per lato, 8 o 10 |
state.blocked_squares | integer[] | Caselle inutilizzabili (solo Octagon, non ordinate) |
state.legs | array | Partite (2 tra bot, 1 contro una persona) |
state.totals | [integer, integer] | Totale pedine delle due partite per partecipante |
state.winner | integer | null | Partecipante vincitore 0 o 1, null in caso di patta |
state.finish_reason | string | null | discs, timeout, double_timeout, disconnect, no_first_move |
Oggetto partita (state.legs[])
| Campo | Tipo | Descrizione |
|---|---|---|
board | integer[64 | 100] | 64 / 100 caselle, 0=vuota 1=nera 2=bianca |
turn | integer | Colore che deve muovere, 1 (nero) o 2 (bianco) |
legal_moves | integer[] | Caselle legali per il colore che deve muovere. Vuoto per le partite concluse |
placed | {"1": integer, "2": integer} | Pedine posate per colore, chiavi "1" (nero) e "2" (bianco) |
black_participant | integer | Partecipante che gioca col nero in questa partita |
clocks_ms | [number, number] | Valori base del tempo residuo in ordine di colore (nero, bianco) |
turn_started_ms | integer | Ora del server all’inizio del turno corrente |
revision | integer | Aumenta di 1 a ogni modifica di questa partita |
status | string | active, finished, timeout, stopped |
history | array | Mosse giocate (color, participant, move, at_ms, eval) |
discs | [integer, integer] | Numero di pedine in ordine di colore (nero, bianco) |
result_discs | [integer, integer] (optional) | Punteggio aggiudicato facoltativo [nero, bianco] per una partita persa per tempo; viene sommato al posto delle pedine. Punteggi per il lato che ha esaurito il tempo e per il suo avversario: std e reversi da 0 a 64, grand da 0 a 100, octagon da 0 a 88, anti da 64 a 0. L'altra partita continua, e i totali decidono il vincitore quando entrambe le partite sono finite. I risultati già conclusi più vecchi non vengono ricalcolati. |
Quando una partita finisce, l’ultimo evento match porta anche record, il registro di partita. Salvalo così com’è per conservare l’intera partita. Registri delle partite
Sincronizzazione
Se la connessione cade o non arrivano eventi per 15 secondi, riconnettiti aumentando l’attesa da 1 a 30 secondi. Scarta gli stati precedenti. Contro una persona confronta nell’ordine room_created_at, round_no e revision. Se perdi la risposta a una mossa, reinviala solo se il turno e la revisione sono invariati.
Invia i dati del motore con agent_environment all’avvio e quando cambiano. Per gli abbinamenti automatici, la v2 ammette al massimo 10 connessioni al flusso e zero chiamate ad agent_poll negli ultimi 10 minuti online.
Autenticazione
Usa HTTPS, JSON POST e Authorization: Bearer. Ogni token vale per un solo bot. Non inserirlo in URL, codice pubblico o log.
Content-Type: application/json
Authorization: Bearer <FS_BOT_TOKEN>POST https://othelloclub.com/flipsight/bot_match_api.php
Opzioni del connettore
Opzioni di tools/bot_match_client.py. È richiesta esattamente una tra --engine e --nboard / --edax / --egaroucid. Il token non è mai un'opzione; viene letto solo dalla variabile d'ambiente FS_BOT_TOKEN. Codici di uscita: 0 arresto normale, 2 token rifiutato, 3 raggiunto --max-runtime.
| Parametri | Descrizione |
|---|---|
--engine "COMMAND" | Avvia questo comando una volta per partita e scambia una riga JSON per mossa senza chiuderne l'input. Un motore che risponde una riga e termina viene riavviato alla mossa successiva. |
--nboard "COMMAND" | Mantiene un motore NBoard per partita, due in totale. Solo standard (std). |
--edax PATH | Edax può collegarsi anche indicando solo il percorso dell’eseguibile con --edax. Non serve un adattatore. Il connettore avvia Edax tramite xboard e invia entrambi i tempi rimasti prima di ogni mossa; Edax decide da sé il tempo di riflessione in base al proprio orologio (connettore v1.4.8 o successivo). Durante la partita Edax mantiene la propria partita e la tabella hash, e con --engine-ponder on cerca anche durante il tempo dell’avversario. --edax-protocol nboard mantiene la vecchia connessione NBoard. |
--edax-eval PATH | Percorso di eval.dat di Edax. Se omesso, cerca data/eval.dat nella cartella dell’eseguibile o in quella superiore. |
--edax-protocol xboard|nboard | Modalità di collegamento di --edax. Il valore predefinito, xboard, lascia che Edax gestisca il proprio orologio e faccia ponder (v1.4.8 o successivo). nboard è il collegamento usato fino a v1.4.7: il connettore stabilisce il tempo di ogni mossa e Edax non fa ponder. |
--egaroucid PATH | Preparate Egaroucid for Console. Scegliete l’eseguibile console e mantenete resources al suo posto. Su macOS e Linux, usate un eseguibile compilato seguendo le istruzioni ufficiali. Il connettore invia posizione e tempo rimasto con setboard, settime e go, senza adattatore. |
--egaroucid-level N | Si usa con --egaroucid. Da 1 a 60 avvia Egaroucid a quel livello (-level N) e non invia il tempo rimasto (settime); 0 o nessun valore mantiene la modalità a tempo, che segue l'orologio della partita. La modalità a livello non ha un comando per fermare la ricerca: se una mossa supera il limite di --max-think-seconds, il connettore ferma il motore e gioca una mossa legale di riserva. Scegli un livello che finisca con ampio margine entro l'orologio della partita. |
--nboard-depth N | Invia set depth N al motore NBoard. Da 0 a 60; 0 mantiene il valore predefinito del motore. Con --edax è il livello di Edax (20 significa L20); senza valore il livello è 60. Edax gioca la mossa migliore trovata appena raggiunge il livello o finisce il tempo della mossa, a seconda di cosa avviene prima. Con --edax viene inviato tramite xboard come sd N. |
--max-think-seconds S | Secondi massimi di attesa del motore per mossa. Predefinito 10, massimo 300. Mai più del tempo rimasto sull'orologio meno 0,75 secondi. È un limite di sicurezza del connettore; il server non ha un limite di tempo per mossa. Con 0 si elimina il limite per mossa e si usa il tempo di partita rimasto. L'orologio della partita è fissato dal sito e il connettore non può cambiarlo: le partite tra bot e le partite automatiche danno 60 secondi a ogni colore per scacchiera, e chi sfida direttamente il tuo bot sceglie il tempo. Con --edax, Edax stabilisce il tempo di ogni mossa con il proprio orologio entro questo limite; se il limite viene raggiunto, il connettore fa giocare subito a Edax la mossa migliore trovata. |
--engine-name NAME | Nome del motore riportato nelle informazioni del bot (massimo 120 caratteri). Non includere comandi o percorsi. |
--engine-threads N | Thread usati dal motore per partita , mostrati nel profilo. Con --edax o --egaroucid il motore usa questo valore (predefinito 4 se il computer ha più di 4 CPU logiche, altrimenti 1); con --engine viene inviato in ogni richiesta come engine_threads. Usa al massimo 4 thread per motore e 8 in totale per un incontro tra bot con due partite simultanee. Con --engine/--nboard il valore viene richiesto se omesso; questa opzione è obbligatoria in background o senza interazione. |
--engine-hash-mb MB | Dimensione della tabella hash per motore, in MB. Con --edax o --egaroucid la tabella viene impostata alla più grande potenza di due non superiore a questo valore (Edax -h, Egaroucid -hash) e viene segnalata quella dimensione; senza l’opzione Edax usa edax.ini ed Egaroucid 32 MB. Gli altri motori segnalano solo il valore e l’impostazione non cambia. Ogni motore ha la sua tabella, quindi una partita tra bot con due giochi in contemporanea ne usa il doppio. |
--engine-ponder on|off | Ponder (ricerca durante il tempo dell’avversario). Con --egaroucid, on avvia Egaroucid con -ponder e segnala Attivo; usa la CPU anche durante il turno dell’avversario. Con --edax (connettore v1.4.8 o successivo), on fa fare ponder a Edax tramite xboard (hard) e segnala Attivo; con --edax-protocol nboard Edax non fa ponder e on viene rifiutato. Gli altri motori segnalano solo la loro impostazione reale. |
--cpu-name NAME | Nome della CPU da riportare (massimo 120 caratteri). Se omesso, viene rilevato automaticamente. |
--once-match ID | Gestisce solo questo incontro ed esce quando finisce (concluso, annullato, scaduto, rifiutato). Funzionano anche gli ID negativi delle partite contro persone. Per i test, combinalo con --max-runtime. |
--max-runtime S | Chiude i motori ed esce dopo questo numero di secondi (codice di uscita 3). |
--save-games DIR | Se attivo, salva da quel momento ogni partita conclusa in DIR/games-YYYY-MM.ndjson, un registro di partita per riga (disattivato per impostazione predefinita). Le partite finite mentre il connettore era fermo o il flusso era interrotto vengono recuperate con agent_games alla riconnessione, a partire dall’ultima partita salvata. Una partita occupa circa 4 KB (circa 6 KB su 10×10), quindi 1.400 partite al giorno fanno circa 6 MB al giorno e 180 MB al mese. Elimina tu i file dei mesi vecchi quando non ti servono più. |
--timing-log PATH | Aggiunge una riga per mossa con la ripartizione del tempo (ricezione della mossa, attesa di una ricerca libera, motore, invio della mossa). Disattivato per impostazione predefinita; al server non viene inviato nulla in più. |
--api URL, --stream-url URL | Indirizzi dell'API e del flusso. Di norma mantieni i valori predefiniti. È accettato solo HTTPS e, poiché il token viene inviato insieme, il flusso deve trovarsi sull'host dell'API. |
Varianti
Un bot riceve solo i giochi selezionati in Giochi supportati. Il game_mode nelle richieste al motore e nello stato dell'incontro indica il gioco. Il server calcola dimensione della scacchiera, caselle bloccate e caselle legali, quindi il motore deve solo scegliere tra le legal_moves ricevute. Non generare le mosse del 10×10 o del Reversi classico con la generazione delle mosse dell'8×8 standard.
| Gioco | game_mode | Scacchiera |
|---|---|---|
| Standard | std | 8×8 |
| Anti | anti | 8×8 |
| Grand (10x10) | grand | 10×10 |
| Octagon | octagon | 10×10 (88) |
| Reversi classico | reversi | 8×8 |
Regole comuni: muove per primo il nero (1). Le due partite partono dalla stessa posizione con i colori invertiti e si giocano contemporaneamente. Nelle coppie di bot, quando non hai mosse legali, legal_moves arriva come array vuoto e il bot deve inviare da sé move=-1 (passo). Il server non passa al posto tuo, e il tuo orologio continua a scorrere. Passare quando esiste una mossa legale è illegale. Una partita finisce quando nessun colore può muovere. Nei nuovi incontri doppi, le caselle vuote di ogni partita conclusa normalmente si aggiungono al colore con più pedine, poi si sommano i punteggi. In Anti vince il totale corretto minore; a parità di pedine non si assegnano caselle vuote. Totali uguali danno patta. Tutte le partite tra bot iniziano da una posizione casuale con 12 pedine. In ogni tipo di gioco, ogni bot ha 1 minuto per partita.
Anti: posare e capovolgere funzionano come nell'Othello standard. Vince il lato con meno pedine sul totale delle due partite.
10x10: regole standard su una scacchiera 10×10 (100 caselle). Le pedine iniziali occupano le quattro caselle centrali; le coppie di bot aggiungono 8 mosse casuali e partono da 12 pedine.
Octagon: stessa scacchiera e stessa disposizione iniziale del 10x10, ma tre caselle in ogni angolo, 12 in totale, sono inutilizzabili (88 caselle giocabili). Le caselle bloccate arrivano come numeri di casella in blocked_squares e come 0, lo stesso valore di vuota, in board. L'array non è in ordine numerico. Non si può giocare su una casella bloccata, e le linee di pedine si fermano lì.
Reversi classico: secondo le regole si parte da una scacchiera vuota. Finché una delle quattro caselle centrali (27, 28, 35, 36) è vuota, si posa solo lì e non si capovolge nulla. Quando tutte e quattro sono occupate, valgono le regole standard. Ogni colore posa al massimo 32 pedine, comprese le prime quattro mosse. placed conta le pedine posate finora da ciascun colore; le sue chiavi sono le stringhe "1" (nero) e "2" (bianco). Le coppie di bot partono dopo che il server ha posato 12 pedine a caso, comprese le quattro mosse centrali, quindi nella prima richiesta i due valori di placed sommano 12 (di solito {"1":6,"2":6}). Un colore che ha posato tutte le 32 pedine riceve legal_moves vuoto e invia -1 a ogni suo turno.
Esempi di richieste al motore per gioco
Esempi della prima richiesta per il nero che il connettore invia a un motore avviato con --engine, generati con il codice delle regole. Le partite reali di ogni tipo partono da una posizione casuale con 12 pedine, quindi board e legal_moves cambiano in ogni partita. Per tenere fissi questi esempi, le loro mosse iniziali sono state scelte vicino al centro della scacchiera. Anche match_id e i valori dell'orologio sono diversi nelle partite reali.
Anti (anti)
JSON in ingresso (connettore → adattatore)
{
"board": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 2, 2, 0, 0, 0, 0, 0, 1, 2, 2, 1, 0, 0, 0, 0, 2, 2, 2, 2, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
"color": 1,
"legal_moves": [2, 3, 12, 25, 42, 44, 45],
"game_mode": "anti",
"board_size": 8,
"blocked_squares": [],
"placed": {
"1": 4,
"2": 4
},
"remaining_ms": 60000,
"match_id": 123,
"leg": 0,
"revision": 0,
"history": [],
"round_no": null,
"room_created_at": null,
"budget_ms": 10000
}JSON di risposta (adattatore → connettore)
{"move":2}Grand (10x10) (grand)
JSON in ingresso (connettore → adattatore)
{
"board": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 2, 0, 0, 0, 0, 0, 0, 0, 1, 2, 2, 1, 0, 0, 0, 0, 0, 0, 2, 2, 2, 2, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
"color": 1,
"legal_moves": [13, 14, 25, 42, 63, 65, 66],
"game_mode": "grand",
"board_size": 10,
"blocked_squares": [],
"placed": {
"1": 4,
"2": 4
},
"remaining_ms": 60000,
"match_id": 123,
"leg": 0,
"revision": 0,
"history": [],
"round_no": null,
"room_created_at": null,
"budget_ms": 10000
}JSON di risposta (adattatore → connettore)
{"move":13}Octagon (octagon)
JSON in ingresso (connettore → adattatore)
{
"board": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 2, 0, 0, 0, 0, 0, 0, 0, 1, 2, 2, 1, 0, 0, 0, 0, 0, 0, 2, 2, 2, 2, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
"color": 1,
"legal_moves": [13, 14, 25, 42, 63, 65, 66],
"game_mode": "octagon",
"board_size": 10,
"blocked_squares": [0, 1, 10, 8, 9, 19, 80, 90, 91, 89, 98, 99],
"placed": {
"1": 4,
"2": 4
},
"remaining_ms": 60000,
"match_id": 123,
"leg": 0,
"revision": 0,
"history": [],
"round_no": null,
"room_created_at": null,
"budget_ms": 10000
}JSON di risposta (adattatore → connettore)
{"move":13}Reversi classico (reversi)
JSON in ingresso (connettore → adattatore)
{
"board": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 2, 2, 1, 1, 0, 0, 0, 0, 2, 2, 1, 1, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
"color": 1,
"legal_moves": [18, 25, 33, 41, 42, 50, 51],
"game_mode": "reversi",
"board_size": 8,
"blocked_squares": [],
"placed": {
"1": 6,
"2": 6
},
"remaining_ms": 60000,
"match_id": 123,
"leg": 0,
"revision": 0,
"history": [],
"round_no": null,
"room_created_at": null,
"budget_ms": 10000
}JSON di risposta (adattatore → connettore)
{"move":18}Campi della richiesta al motore
| Campo | Tipo | Descrizione |
|---|---|---|
game_mode | string | Uno tra std, anti, grand, octagon, reversi. Lo XOT nelle partite contro persone arriva come std. |
board_size | integer 8 | 10 | 8, oppure 10 per grand e octagon. |
board | integer[board_size²] | Array di lunghezza board_size². Si legge da a1 verso destra, poi la riga successiva. 0=vuota (comprese le caselle bloccate di Octagon), 1=nero, 2=bianco. |
blocked_squares | integer[] | Caselle inutilizzabili di Octagon. Array vuoto negli altri giochi. |
placed | {"1": integer, "2": integer} | Pedine posate finora per colore, comprese le mosse iniziali casuali; le chiavi sono le stringhe "1" e "2". Serve per il limite di 32 pedine del Reversi classico. |
legal_moves | integer[] | Caselle in cui puoi giocare adesso. Se è vuoto, rispondi move=-1. |
color | integer 1 | 2 | Colore che deve muovere. 1=nero, 2=bianco. |
budget_ms | integer | Tempo concesso per questa mossa in millisecondi: il minore tra --max-think-seconds e il tempo rimasto sull'orologio meno 0,75 secondi. Se viene superato, il connettore ferma il motore. |
remaining_ms | integer | Tempo rimasto al tuo colore in questa partita, in millisecondi, dopo aver sottratto il tempo già usato in questo turno. |
match_id | integer ≠ 0 | ID dell'incontro. Negativo (-numero della stanza) nelle partite contro persone. |
leg | integer 0 | 1 | Numero di partita 0 o 1. Sempre 0 nelle partite contro persone. |
revision | integer | Numero di stato di questa partita. Invialo invariato con agent_move. |
history | array | Mosse giocate in questa partita. Decidi in base a board. |
round_no | integer | null | Numero del turno di gioco di una partita contro una persona. null per le coppie di bot. |
room_created_at | string | null | Ora di creazione della stanza di una partita contro una persona. null per le coppie di bot. |
engine_threads | integer (optional) | Presente solo se il programma di connessione è stato avviato con --engine-threads. Thread che il motore può usare per questa partita; dimensiona la ricerca di conseguenza. |
Sfidare un altro bot in una variante
Aggiungi game_mode ad agent_challenge; il valore predefinito è std. Entrambi i bot devono averlo in supported_games. Vedi i giochi dell'avversario nella pagina dei bot. Se a uno dei due bot manca il gioco, la risposta è HTTP 409 con l'errore qui sotto.
{"action":"agent_challenge","target_id":2,"game_mode":"anti"}
{"action":"agent_challenge","target_name":"Opponent","game_mode":"grand"}HTTP 409
{"ok":false,"error":"unsupported game mode","server_now_ms":1800000000000}Modificare supported_games
Il modulo di registrazione parte con Standard selezionato, e i bot più vecchi senza un elenco salvato supportano std. Puoi modificare l'elenco solo in Gestisci nella pagina web dei bot, mai con il token del bot (API). La modifica viene rifiutata mentre un incontro è in corso o in attesa di accettazione. Un elenco vuoto non si può salvare.
Persone contro bot registrati
Le persone possono sfidare il tuo bot in qualsiasi gioco registrato per lui. Se supporta lo standard, possono arrivare sia STD sia XOT. Lo XOT arriva con game_mode std e parte da una scacchiera in cui sono già state giocate 8 mosse (sono incluse in history). Chi sfida sceglie l'orologio, e la partita non è classificata. Un incontro contro una persona ha una sola partita (leg 0) e un match_id negativo. Il server gestisce i passi quando non ci sono mosse possibili, quindi non inviare -1. I bot registrati online con abbinamento automatico attivo partecipano anche alle partite rapide STD/XOT supportate. Queste sono classificate per i membri e non classificate per gli ospiti.
Mosse illegali e tempo
Una mossa illegale o una revision superata viene rifiutata con HTTP 409 (illegal_move, stale_revision, not_your_turn) e la scacchiera non cambia. Nel frattempo l'orologio continua a scorrere. Il connettore invia di nuovo la stessa mossa con la stessa revision, quindi, se il motore non viene corretto, quella partita finisce per essere persa per tempo. Il server non ha limiti per mossa e controlla solo il tempo rimasto di ciascun colore. I 10 secondi sono il valore predefinito di --max-think-seconds del connettore.
Regole dell’incontro
Tutte le partite tra bot iniziano da una posizione casuale con 12 pedine. Due partite si svolgono contemporaneamente a colori invertiti. Vince il totale maggiore di pedine, oppure quello minore in Anti.
In ogni tipo di gioco, ogni bot ha 1 minuto per partita.
Se un bot non ha giocato la prima mossa entro 30 secondi dall’inizio, l’incontro viene annullato e non è classificato. Se durante l’incontro la connessione di un bot si interrompe per più di 30 secondi mentre l’altro è connesso, vince il bot connesso (finish_reason: disconnect) e il risultato è classificato.
Il server calcola le mosse dei bot FlipSight in tutti i tipi di gioco. Sono accettate sia le sfide dal web sia quelle tramite API (agent_challenge), e il server avvia subito l'incontro, quindi non serve tenere aperta la stanza di gioco. Se il calcolo del server si ferma per più di 30 secondi, l'incontro viene annullato (finish_reason: technical) e non è classificato. Le varianti sono costose da calcolare, quindi si giocano al massimo 2 incontri di variante contro bot FlipSight alla volta. Se i posti sono pieni ricevi HTTP 409 con site bot variant matches are full; riprova tra poco.
L’abbinamento automatico accoppia bot distanti al massimo 500 punti in una variante scelta da entrambi. Il connettore ha 120 secondi per accettare e il risultato vale per la classifica. In Gestisci puoi scegliere le varianti o disattivare l’abbinamento automatico. Un bot avviato con il motore di prova (environment.practice è true) resta escluso dagli incontri automatici, e i suoi incontri contro altri bot in quel periodo non sono classificati.
Una sfida umana diretta si gioca in una stanza normale, con gioco e tempo supportati. Il server rende sempre non classificate le sfide dirette. I bot registrati online con abbinamento automatico attivo partecipano anche alle partite rapide STD/XOT supportate. Queste sono classificate per i membri e non classificate per gli ospiti. Un bot registrato accetta solo tante partite quante ne indica l'impostazione delle partite simultanee (predefinito 2). Una partita contro una persona e un incontro tra bot (due scacchiere) contano 1 ciascuno.
Svolgimento dell’incontro
pending → running → finished / aborted
pending → rejected / expired
kind=human: id=-room_id, legs[0], round_no, room_created_at
agent_move: move=19 / "d3" / "D3" (8×8)
10×10: "j10" = "J0" = 99
pass: -1 / "pass" / "PA" / "PS" / "--" (paired games only)
index=row*board_size+column (0-based)Tutte le partite tra bot iniziano da una posizione casuale con 12 pedine. Due partite si svolgono contemporaneamente a colori invertiti. Vince il totale maggiore di pedine, oppure quello minore in Anti.
Il tuo numero di partecipante è 0 se sei bot_a e 1 se sei bot_b. Il partecipante 0 gioca col nero (1) in legs[0] e col bianco (2) in legs[1]; il partecipante 1 il contrario. Tocca a te quando leg.status è active e leg.turn corrisponde al tuo colore. Può toccare a te in entrambe le partite contemporaneamente.
Se non hai mosse legali, devi inviare tu stesso move -1 (passo); il server non passa al posto tuo. Nelle partite contro una persona il server gestisce i passi come nelle normali sale di gioco.
Nel tuo turno, tempo residuo = clocks_ms[tuo colore - 1] - (server_now_ms - turn_started_ms). clocks_ms segue l’ordine dei colori (nero, bianco); totals e winner seguono l’ordine dei partecipanti (winner 0 o 1, null in caso di patta).
Numeri delle caselle
Numero di casella = riga × 8 + colonna, quindi a1=0, h1=7, a2=8 e h8=63. Ad esempio, 19 è d3 e 37 è f5. L’array board usa lo stesso ordine, con 0=vuota, 1=nera, 2=bianca.
a b c d e f g h
1 0 1 2 3 4 5 6 7
2 8 9 10 11 12 13 14 15
3 16 17 18 19 20 21 22 23
4 24 25 26 27 28 29 30 31
5 32 33 34 35 36 37 38 39
6 40 41 42 43 44 45 46 47
7 48 49 50 51 52 53 54 55
8 56 57 58 59 60 61 62 63Su 10×10 (grand, octagon), casella = riga × 10 + colonna. Le colonne vanno da a a j, e la decima riga si scrive 10 o 0 nelle coordinate. a1=0, j1=9, a2=10, j10=99 (uguale a j0). La stessa coordinata ha un numero diverso per ogni dimensione della scacchiera: d3 è 19 su 8×8 e 23 su 10×10.
a b c d e f g h i j
1 0 1 2 3 4 5 6 7 8 9
2 10 11 12 13 14 15 16 17 18 19
3 20 21 22 23 24 25 26 27 28 29
4 30 31 32 33 34 35 36 37 38 39
5 40 41 42 43 44 45 46 47 48 49
6 50 51 52 53 54 55 56 57 58 59
7 60 61 62 63 64 65 66 67 68 69
8 70 71 72 73 74 75 76 77 78 79
9 80 81 82 83 84 85 86 87 88 89
10 90 91 92 93 94 95 96 97 98 99Octagon (octagon)
a b c d e f g h i j
1 ## ## 2 3 4 5 6 7 ## ##
2 ## 11 12 13 14 15 16 17 18 ##
3 20 21 22 23 24 25 26 27 28 29
4 30 31 32 33 34 35 36 37 38 39
5 40 41 42 43 44 45 46 47 48 49
6 50 51 52 53 54 55 56 57 58 59
7 60 61 62 63 64 65 66 67 68 69
8 70 71 72 73 74 75 76 77 78 79
9 ## 81 82 83 84 85 86 87 88 ##
10 ## ## 92 93 94 95 96 97 ## ##Adattatore motore
Il connettore dei bot FlipSight (Python 3.9+, solo libreria standard) funziona su Windows, macOS e Linux e collega un motore in due modi. --engine avvia il motore una volta per partita, invia una riga JSON a ogni mossa e legge una riga {"move": casella}. Un motore che risponde una riga e termina funziona comunque, perché viene riavviato alla mossa successiva, ma un motore che legge l'input fino alla fine (sys.stdin.read() ecc.) non risponde mai: leggi una riga alla volta. legal_moves nella richiesta elenca le caselle legali; se è vuota, rispondi -1. --nboard tiene in esecuzione un motore NBoard, uno per partita; imposta la profondità con --nboard-depth.
Azioni API
Gli esempi di risposta mostrano il formato. Il pulsante di copia copia solo la richiesta e non chiama l’API.
POST agent_environment
Comunica ambiente
Comunica CPU, sistema operativo, nome del motore, thread e modalità allenamento (practice) del PC del connettore. Invialo all'avvio e quando i valori cambiano. La risposta contiene il tuo bot.
| Parametri | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
action | string "agent_environment" | Obbligatorio | Nome dell’azione da chiamare |
environment | object | Obbligatorio | CPU, sistema operativo e nome del motore del PC del connettore (fino a 120 caratteri ciascuno, facoltativo) e practice (true o false, facoltativo). practice a true significa che il bot si sta allenando: resta escluso dagli incontri automatici e gli incontri tra bot richiesti o accettati nel frattempo non sono classificati. Il connettore lo invia da solo quando viene avviato con il motore di prova. Il server ricorda l'ultimo valore, quindi a fine allenamento invialo senza practice o con false. hash_mb (MB): Per motore. Se il connettore non indica il valore, inseriscilo. ponder (true / false / null): Solo visualizzazione. Se non segnalato, scegli il valore. Modifica il motore per cambiarlo davvero. |
Esempio richiesta
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_environment","environment":{"cpu":"Apple M4","engine":"MyEngine","os":"Darwin","engine_threads":1,"hash_mb":32,"ponder":false}}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_environment","environment":{"cpu":"Apple M4","engine":"MyEngine","os":"Darwin","engine_threads":1,"hash_mb":32,"ponder":false}}'Esempio risposta
{
"ok": true,
"bot": {
"id": 2,
"name": "MyBot",
"owner_id": "example",
"owner_name": "Example",
"owner": {
"player_id": "example",
"name": "Example",
"photo": "/img/no_profile.gif",
"country_code": "",
"country_name": "",
"country_flag_url": "",
"donor": false,
"verified_player_id": ""
},
"engine_level": null,
"rating": {
"rating": 1200,
"rd": 300,
"official": false,
"official_progress": {
"kind": "provisional",
"current": 0,
"required": 50
},
"color": "pz-rating-unofficial",
"high_rating": 1200,
"wins": 0,
"losses": 0,
"draws": 0,
"streak": 0,
"best_streak": 0
},
"supported_games": ["std", "anti"],
"auto_match": true,
"bio": "",
"registered_at": "2026-11-12 18:00:00",
"registered_at_ts": 1794474000,
"environment": {
"cpu": "Apple M4",
"engine": "MyEngine",
"os": "Darwin",
"practice": false,
"engine_threads": 1,
"hash_mb": 32,
"ponder": false
},
"env": {
"cpu": "Apple M4",
"engine_threads": 1,
"hash_mb": 32,
"hash_mb_reported": 32,
"hash_mb_override": null,
"ponder": false,
"ponder_reported": false,
"ponder_override": null,
"cpu_override": null,
"engine_threads_override": null,
"cpu_reported": "Apple M4",
"engine_threads_reported": 1
},
"is_builtin": false,
"online": true,
"disabled": false,
"deleted": false,
"photo": "/flipsight/bot_match_api.php?action=photo&bot_id=2&v=1794474000000"
},
"server_now_ms": 1800000000000
}POST agent_challenge
Sfida
Indica target_id (numero del bot) o target_name (nome del bot), indicati nella pagina dei bot. Anche i bot FlipSight integrati (is_builtin: true) si possono sfidare tramite API in tutti i tipi di gioco, e il server avvia subito l'incontro. Se ci sono già 2 incontri di variante contro bot integrati, ricevi HTTP 409 con site bot variant matches are full. Se il bot destinatario ha disattivato «Sfide dai bot» nella gestione dei bot, ricevi HTTP 409 con bot does not accept bot challenges. Le partite automatiche tra bot non dipendono da questa impostazione e seguono quella di abbinamento automatico.
Puoi sfidare lo stesso bot tre volte di fila. Attendi cinque minuti dalla fine del terzo incontro.
| Parametri | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
action | string "agent_challenge" | Obbligatorio | Nome dell’azione da chiamare |
target_id | integer ≥ 1 | Facoltativo | ID del bot da sfidare |
target_name | string | Facoltativo | Nome del bot da sfidare (al posto di target_id) |
game_mode | string std | anti | octagon | grand | reversi | Facoltativo | Gioco per una coppia di bot. Predefinito std. Entrambi i bot devono supportarlo. Standard / Anti / Octagon / Grand (10x10) / Reversi classico |
Esempio richiesta
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_challenge","target_id":2,"game_mode":"anti"}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_challenge","target_id":2,"game_mode":"anti"}'Esempio risposta
{
"ok": true,
"match_id": 123,
"server_now_ms": 1800000000000
}POST agent_accept
Accetta
| Parametri | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
action | string "agent_accept" | Obbligatorio | Nome dell’azione da chiamare |
match_id | integer ≥ 1 | Obbligatorio | ID dell’incontro (negativo nelle partite contro una persona) |
Esempio richiesta
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_accept","match_id":123}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_accept","match_id":123}'Esempio risposta
{
"ok": true,
"match": {
"id": 123,
"status": "running",
"bot_a": 1,
"bot_b": 2
},
"server_now_ms": 1800000000000
}POST agent_reject
Rifiuta
| Parametri | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
action | string "agent_reject" | Obbligatorio | Nome dell’azione da chiamare |
match_id | integer ≥ 1 | Obbligatorio | ID dell’incontro (negativo nelle partite contro una persona) |
Esempio richiesta
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_reject","match_id":123}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_reject","match_id":123}'Esempio risposta
{
"ok": true,
"match": {
"id": 123,
"status": "rejected",
"bot_a": 1,
"bot_b": 2
},
"server_now_ms": 1800000000000
}POST agent_move
Invia mossa
| Parametri | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
action | string "agent_move" | Obbligatorio | Nome dell’azione da chiamare |
match_id | integer ≠ 0 | Obbligatorio | ID dell’incontro (negativo nelle partite contro una persona) |
round_no | integer ≥ 0 | Obbligatorio contro una persona | Solo partite contro una persona: round_no dall’oggetto incontro |
room_created_at | string | Obbligatorio contro una persona | Solo partite contro una persona: room_created_at dall’oggetto incontro |
leg | integer 0 | 1 | Obbligatorio | Partita 0 o 1 (0 nelle partite contro una persona) |
revision | integer ≥ 0 | Obbligatorio | revision della partita per cui è stata calcolata la mossa; 409 stale_revision se la partita è cambiata |
move | integer -1..99 | string | Obbligatorio | Casella 0-(board_size²−1), -1 per passare / d3 / D3 / pass |
eval | number -100..100 | Facoltativo | La valutazione del tuo motore dopo questa mossa, in pedine dal tuo lato (+ significa che sei in vantaggio, con 2 decimali). Arriva fino al numero di caselle giocabili: da -64 a 64 su 8x8, da -100 a 100 su 10x10 e da -88 a 88 sull’ottagono. Se la ometti o invii un valore non valido, si scarta solo la valutazione e la mossa viene accettata. Solo gli incontri tra bot la conservano, tutti la vedono durante la partita, anche il bot avversario, e le partite contro persone la ignorano. |
Esempio richiesta
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_move","match_id":123,"leg":1,"revision":0,"move":2,"eval":1.5}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_move","match_id":123,"leg":1,"revision":0,"move":2,"eval":1.5}'Persone contro bot registrati
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_move","match_id":-45,"leg":0,"revision":0,"move":"d3","round_no":1,"room_created_at":"2026-11-12 19:00:00"}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_move","match_id":-45,"leg":0,"revision":0,"move":"d3","round_no":1,"room_created_at":"2026-11-12 19:00:00"}'Esempio risposta
{
"ok": true,
"match": {
"id": 123,
"status": "running",
"bot_a": 1,
"bot_b": 2
},
"server_now_ms": 1800000000000
}POST agent_games
Scarica i registri delle partite
Restituisce le partite concluse del tuo bot come registri di partita. La risposta è NDJSON (Content-Type application/x-ndjson), con una partita per riga. Include gli incontri tra bot e le partite contro persone, ma non le partite di allenamento né le partite contro l’account del sito othelloclub. Gli annullamenti tecnici sono inclusi con result void.
Questa richiesta non mette il tuo bot online e non conta per la verifica della specifica API v2. Ogni bot può chiamarla una volta ogni 5 secondi; una chiamata più rapida riceve 429 con retry_after_sec. Invia Accept-Encoding: gzip per ricevere una risposta compressa.
| Parametri | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
action | string "agent_games" | Obbligatorio | Nome dell’azione da chiamare |
since | integer ≥ 0 | Facoltativo | updated_ms più vecchio da includere, in ms. Predefinito 0. |
until | integer ≥ 0 | Facoltativo | updated_ms più recente da includere, in ms. Predefinito: adesso. |
max | integer 1..300 | Facoltativo | Numero massimo di partite per risposta, da 1 a 300. Predefinito 100. |
games | array | Facoltativo | Giochi da includere (std, anti, octagon, grand, reversi). Predefinito: tutti. |
order | string asc | desc | Facoltativo | asc: prima le più vecchie (predefinito). desc: prima le più recenti. |
Esempio richiesta
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_games","since":1799913600000,"max":100}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_games","since":1799913600000,"max":100}'Esempio risposta
{
"format": 1,
"kind": "bot",
"id": 123,
"url": "https://othelloclub.com/flipsight/lab?match_id=123",
"game_mode": "std",
"opening_mode": "random12",
"board_size": 8,
"time_limit_sec": 60,
"auto": true,
"ranked": true,
"rating_applied": true,
"status": "finished",
"finish_reason": "discs",
"result": "win",
"started_ms": 1799999962428,
"finished_ms": 1800000000000,
"updated_ms": 1800000000000,
"me": {
"bot_id": 2,
"name": "MyBot",
"engine": "MyEngine",
"rating_before": 2138.51,
"rating_after": 2143.53
},
"opponent": {
"kind": "bot",
"bot_id": 9,
"name": "Ethan",
"builtin": true,
"engine": null,
"rating_before": 2017.41,
"rating_after": 2017.41
},
"discs": [73, 55],
"opening": "e6f6d3e7f5e3f7c4",
"opening_squares": [44, 45, 19, 52, 37, 20, 53, 26],
"opening_colors": "BWBWBWBW",
"legs": [
{
"my_color": "W",
"status": "finished",
"discs": [28, 36],
"result_discs": [28, 36],
"colors": "BWB",
"moves": "f3f4c3",
"squares": [21, 29, 18],
"at_ms": [1799999962491, 1799999965034, 1799999965089],
"used_ms": [63, 1111, 55],
"left_ms": [59937, 58889, 59882],
"evals": [null, -1.5, null]
},
{
"my_color": "B",
"status": "finished",
"discs": [37, 27],
"result_discs": [37, 27],
"colors": "BWB",
"moves": "b3b4c3",
"squares": [17, 25, 18],
"at_ms": [1799999963923, 1799999964158, 1799999965481],
"used_ms": [1495, 235, 1323],
"left_ms": [58505, 59765, 57182]
}
]
}Registri delle partite
Un registro di partita (record) è un oggetto JSON per una partita conclusa. Contiene giocatori, risultato, punteggi di classifica, apertura e orario di ogni mossa, dal lato del tuo bot. Ricevi lo stesso oggetto in due punti.
- Evento di fine partita: Quando una partita finisce, l’ultimo evento match (status finished o aborted) porta record.
- agent_games: Restituisce le partite concluse, una per riga. Usalo per le partite passate e per quelle che ti sono sfuggite.
Le mosse usano la notazione delle partite del sito. Ogni mossa ha due caratteri, e il passo è pa. Le colonne vanno da a a j e le righe da 1 a 9; su 10×10 la decima riga è 0 (j0 è la casella 99). squares dà le stesse mosse come numeri di casella (-1 per un passo), e colors indica il lato che ha mosso, B o W.
Le partite che finiscono mentre il flusso è interrotto e le partite contro persone il cui registro di partita non è ancora pronto non portano record nell’evento di fine partita. Colma questi vuoti con agent_games come segue.
- Punto di partenza: Invia come since l’updated_ms del tuo registro di partita salvato più recente. since è inclusivo, quindi il tuo ultimo registro di partita arriva di nuovo.
- Salta i doppioni: Salta un registro di partita di cui hai già kind e id.
- Pagina successiva: Richiama con l’updated_ms più recente ricevuto. Fermati quando una risposta non porta nuovi registri di partita.
- Registri di partita modificati: Una partita che cambia dopo la fine, come in un annullamento tecnico, arriva di nuovo con un updated_ms più recente. Sostituisci il vecchio registro di partita con quello nuovo.
Campi del registro di partita
| Campo | Tipo | Descrizione |
|---|---|---|
format | integer | Versione del formato del registro di partita, ora 1. Alla versione 1 possono aggiungersi nuovi campi; il numero sale solo quando un campo esistente cambia significato. |
kind | string | bot: un incontro tra bot in due partite. human: una sola partita contro una persona. |
id | integer | L’ID dell’incontro tra bot per kind bot, l’ID della partita per kind human. kind e id insieme identificano un registro di partita. |
url | string | Pagina per rivedere la partita |
room_id, round_no | integer | null | Solo partite contro una persona: stanza e turno |
game_mode | string | Gioco (std, anti, grand, octagon, reversi) |
opening_mode | string | random12: l’inizio casuale con 12 pedine di un incontro tra bot. xot o std: come è iniziata una partita contro una persona. |
board_size | integer 8 | 10 | Caselle per lato, 8 o 10 |
time_limit_sec | integer | Secondi per partita e per colore |
auto | boolean | Creato dall’abbinamento automatico |
ranked | boolean | Se l’incontro è classificato |
rating_applied | boolean | Se il risultato ha cambiato la classifica |
status | string | finished, oppure aborted per un annullamento tecnico |
finish_reason | string | null | Perché la partita è finita: gli stessi valori di state.finish_reason per gli incontri tra bot, il valore della stanza di gioco per le partite contro una persona. |
result | string | win, loss, draw o void, dal lato del tuo bot |
started_ms, finished_ms, updated_ms | integer | null | Ora di inizio e di fine in ms; started_ms è null nelle partite contro una persona. updated_ms è quando il registro di partita è cambiato l’ultima volta, di solito l’ora di fine, e since e until si confrontano con questo valore. |
me | object | Il tuo bot: bot_id, name, engine, rating_before, rating_after. engine è il nome del motore comunicato all’inizio; entrambi i punteggi sono null se la partita non era valida per la classifica. |
opponent | object | Avversario: kind (bot, human o guest), name, engine, rating_before, rating_after. Un bot ha anche bot_id e builtin, una persona player_id. |
discs | [integer, integer] | Punteggio del tuo bot e dell’avversario: il totale delle due partite (state.totals) per gli incontri tra bot, il numero di pedine per le partite contro una persona. |
opening, opening_squares, opening_colors | string, integer[], string | Mosse d’apertura prima delle partite, nella stessa notazione: l’inizio casuale con 12 pedine o l’apertura XOT. |
legs[].my_color | string | Colore del tuo bot in questa partita, B o W |
legs[].status | string | active, finished, timeout, stopped |
legs[].discs | [integer, integer] | Numero di pedine in ordine di colore (nero, bianco) |
legs[].result_discs | [integer, integer] (optional) | Punteggio aggiudicato facoltativo [nero, bianco] per una partita persa per tempo; viene sommato al posto delle pedine. Punteggi per il lato che ha esaurito il tempo e per il suo avversario: std e reversi da 0 a 64, grand da 0 a 100, octagon da 0 a 88, anti da 64 a 0. L'altra partita continua, e i totali decidono il vincitore quando entrambe le partite sono finite. I risultati già conclusi più vecchi non vengono ricalcolati. |
legs[].moves, squares, colors | string, integer[], string | Le mosse della partita dopo l’apertura: moves come stringa, squares come numeri, colors come B o W per ogni mossa. |
legs[].at_ms, used_ms, left_ms | (integer | null)[] | Per ogni mossa: quando è stata giocata in ms, il tempo usato e il tempo rimasto poi sull’orologio di chi ha mosso. Gli orari di gioco sono null nelle partite contro persone, e anche i valori sconosciuti sono null. |
legs[].evals | (number | null)[] (optional) | La valutazione che chi ha mosso ha inviato con la mossa, in pedine dal suo lato. Le mosse inviate senza valutazione hanno null. Il campo manca se nessuna mossa della partita ne aveva una. |
Errori
Gli errori hanno la forma {"ok": false, "error": "…"}. Con 401 fermati e verifica il token. Con 409 controlla turno, revision e mosse legali nel tuo stato più recente (se non sei sicuro, ricollega il flusso). 410 indica che l’azione è stata rimossa (agent_poll dal 2026-11-22 00:00 (UTC+9)): usa il flusso di eventi. 429 indica troppe richieste (più di 20 al secondo da un bot, o 40 al secondo da tutti i bot di uno stesso IP, verso bot_match_api.php). Con 429, 5xx ed errori di connessione reinvia la stessa richiesta dopo 0,2-0,5 s (rispetta Retry-After se presente) e allunga l’attesa dopo alcuni tentativi. Non reinviare mai una mossa illegale.
{"ok":false,"error":"stale_revision","server_now_ms":1800000000000}| HTTP | error |
|---|---|
| 400 | JSON object required / unknown action |
| 401 | invalid bot credential |
| 403 | access denied / invalid csrf |
| 405 | POST required |
| 409 | stale_revision / not_your_turn / illegal_move / leg_finished / match not running / match timed out / stale room revision / invalid move coordinate / move outside board / unsupported game mode / both bots must be connected / bot already has an active match / bot busy / engine thread limit exceeded / bot challenge repeat limit / challenge expired or answered / site bot variant matches are full / target bot not found |
| 410 | agent_poll was removed; use bot-stream |
| 413 | request too large |
| 429 | Too many requests (bot_match_api.php rate limit) |
| 503 | bot match storage unavailable |
agent_poll
Leggi stato (rimosso il 2026-11-22)
Rimosso il 2026-11-22 00:00 (UTC+9): da allora restituisce HTTP 410 {"ok": false, "error": "agent_poll was removed; use bot-stream"}. Ricevi il tuo stato dal flusso di eventi e ricollegalo per risincronizzarti. Fino ad allora risponde ancora, ma dal 2026-11-21 23:40 (UTC+9) un bot registrato che lo ha chiamato negli ultimi 10 minuti viene escluso dagli abbinamenti automatici.
Implementare l'API da soli