Guide pas à pas pour débutants
Ce qu'il vous faut
- Un compte FlipSight.
- Une photo du bot : un fichier GIF, JPG ou PNG de 5 Mo au maximum, d'au moins 175 px de large et de haut.
- Votre ordinateur pour faire fonctionner le bot Les coups de votre bot sont calculés sur l'ordinateur où tourne le connecteur. Même avec le même moteur, la force peut varier selon la puissance de l'ordinateur et les réglages du moteur, et si vous changez d'ordinateur ou de réglages, le classement peut évoluer en conséquence.
- Python 3, un programme gratuit qui fait tourner le connecteur. La version 3.9 ou ultérieure fonctionne ; la 3.11 ou ultérieure est recommandée. Vous le vérifiez à l'étape 5.
- Le moteur de votre bot. Un moteur d’entraînement pour les tests est fourni avec le programme de connexion.
1. Enregistrer votre bot
Connectez-vous et ouvrez la page des bots (othelloclub.com/fr/flipsight/lab). Dans le bloc Enregistrer mon bot en haut, saisissez un nom dans Nom du bot (2 à 24 caractères). Dans Jeux pris en charge, laissez pour l'instant seulement Standard coché. Choisissez une image dans Envoyer une photo du bot, puis appuyez sur le bouton Enregistrer mon bot.
Résultat attendu : le bloc Jeton de connexion (affiché une seule fois) apparaît avec un long texte commençant par fsbm_.
2. Conserver le jeton
Ce long texte est le jeton, un mot de passe propre à votre bot. Le connecteur s'en sert pour prouver au serveur qu'il agit pour ce bot. Copiez-le en entier et collez-le temporairement quelque part, par exemple dans un éditeur de texte. Une fois le bloc fermé, vous ne pourrez plus revoir ce même jeton.
Traitez le jeton comme un mot de passe. Ne le montrez à personne et n'en publiez pas de capture d'écran. Si vous le perdez ou si quelqu'un l'a vu, ouvrez Gérer dans la liste des bots et appuyez sur Créer un jeton de connexion. Dès que vous obtenez un nouveau jeton, l'ancien cesse immédiatement de fonctionner.
3. Télécharger le connecteur
Appuyez sur Télécharger les exemples Python pour télécharger le fichier ZIP, puis décompressez-le. Ce guide appelle le dossier décompressé « dossier du bot ». Placez-le dans un endroit facile à retrouver, comme le bureau.
Résultat attendu : le dossier du bot contient le fichier README.md et le dossier tools.
4. Ouvrir un terminal dans le dossier du bot
Un terminal est une fenêtre où l'on tape des commandes. Ouvrez-le comme suit selon votre système.
macOS : appuyez sur Command+Space, tapez Terminal et ouvrez-le. Tapez cd suivi d'une espace, faites glisser le dossier du bot dans la fenêtre, puis appuyez sur Entrée.
Linux : dans le gestionnaire de fichiers, faites un clic droit sur le dossier du bot et choisissez « Ouvrir dans un terminal ». Le nom du menu peut varier selon la distribution. S'il n'existe pas, ouvrez un terminal et utilisez cd comme sous macOS.
Windows : ouvrez le dossier du bot dans l'Explorateur de fichiers. Tapez powershell dans la barre d'adresse en haut et appuyez sur Entrée. Une fenêtre PowerShell s'ouvre dans ce dossier.
Vérification : tapez la commande ci-dessous et appuyez sur Entrée. C'est réussi si README.md et tools apparaissent dans la liste. Cette commande est la même sous macOS, Linux et Windows PowerShell.
ls5. Vérifier Python
Dans la même fenêtre, copiez la commande correspondant à votre système, collez-la et appuyez sur Entrée. Vous pouvez utiliser le bouton de copie en haut à droite de chaque bloc de code.
macOS / Linux
python3 --versionWindows PowerShell
py --versionRésultat attendu : une version commençant par 3, par exemple Python 3.11.9. La version 3.9 ou ultérieure fonctionne. Si la commande est introuvable, installez Python comme indiqué ci-dessous, fermez la fenêtre et recommencez à l'étape 4.
macOS : téléchargez l'installateur macOS (.pkg) sur python.org et installez-le. Exécutez ensuite une fois Install Certificates.command depuis le dossier Python dans Applications. Cela prépare les certificats nécessaires aux connexions sécurisées (HTTPS).
Linux : installez python3 avec la logithèque ou le gestionnaire de paquets de votre distribution.
Windows : installez le Python install manager depuis python.org.
6. Saisir le jeton
Placez le jeton dans une variable d'environnement, un réglage temporaire qui n'existe que dans cette fenêtre de terminal. Son nom est FS_BOT_TOKEN. Copiez ci-dessous la commande d'une ligne pour votre système, collez-la et appuyez une fois sur Entrée. Bot token s'affiche alors et attend votre saisie. Collez maintenant le jeton copié à l'étape 2 et appuyez sur Entrée.
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)).PasswordSous macOS et Linux, le jeton collé ne s'affiche pas, et sous Windows vous voyez des * à la place de ses caractères. Les deux cas sont normaux. Comme le jeton n'est pas écrit dans la commande, il ne reste pas dans l'historique des commandes. Le réglage ne vaut que pour cette fenêtre. Si vous l'avez fermée ou avez ouvert une nouvelle fenêtre, refaites les étapes 4 et 6.
Dans PowerShell, collez le jeton avec Ctrl+V.
Résultat attendu : l'invite de la commande suivante revient sans erreur.
7. Lancer le connecteur
Dans la même fenêtre, copiez la commande ci-dessous telle quelle, collez-la et appuyez sur Entrée. Ne modifiez pas les noms de fichiers qu'elle contient. Votre bot se connecte avec le moteur d'entraînement, un moteur très faible qui joue la case légale de plus petit numéro.
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'Il est normal que la commande n’affiche aucun texte et ne rende pas la main pendant son exécution. Pour garder votre bot en ligne, laissez cette fenêtre ouverte avec le programme de connexion et le moteur en marche, et empêchez votre ordinateur de se mettre en veille. Fermer cette fenêtre ou appuyer sur Ctrl+C arrête les deux programmes et met votre bot hors ligne. Relancez la commande ci-dessus pour le remettre en ligne. Le programme de connexion accepte automatiquement les demandes des autres bots.
Tant que le bot tourne avec le moteur d'entraînement, il n'obtient aucun match automatique, et ses matchs contre d'autres bots, même ceux que vous demandez, ne sont pas classés. Relancez-le avec votre propre moteur (étape 10) et il sera apparié et classé à partir de ce moment.
Résultat attendu : dans la liste Bots enregistrés de la page des bots, le point à droite du nom de votre bot est vert. En le survolant, vous voyez En ligne.
8. Tester avec une première partie
Sur la page des bots, choisissez votre bot dans Mon bot joueur. Choisissez n'importe quel bot dans la liste Bots FlipSight, appuyez sur Défier et confirmez dans la fenêtre qui s'ouvre. Dans tous les types de jeu, le serveur calcule les coups des bots FlipSight : inutile de garder la salle de jeu ouverte.
Résultat attendu : la salle de jeu affiche deux plateaux et un pion est posé à chaque tour de votre bot. Le moteur d'entraînement est très faible, il est donc normal de perdre.
9. Continuer après la fermeture de la fenêtre (facultatif)
Après la première partie, arrêtez le connecteur avec Ctrl+C dans la fenêtre de l’étape 7. Relancez-le dans cette fenêtre avec la commande ci-dessous. Laissez l’ordinateur en éveil.
macOS / Linux
Utilisez screen et remplacez mybot par un nom différent pour chaque bot. Après le lancement, appuyez sur Ctrl+A puis sur D pour pouvoir fermer la fenêtre. Pour arrêter ce bot, revenez à sa session avec la commande du bas et appuyez sur Ctrl+C.
Lancer
screen -S mybot python3 tools/bot_match_client.py --engine-threads 1 --engine 'python3 tools/bot_match_example_engine.py'Arrêter
screen -r mybotWindows PowerShell
Windows : une fenêtre réduite apparaît dans la barre des tâches et le bot y tourne. Vous pouvez fermer la fenêtre PowerShell actuelle. Pour l'arrêter, ouvrez la fenêtre réduite et appuyez sur Ctrl+C, ou fermez cette fenêtre.
Lancer
Start-Process py -ArgumentList 'tools/bot_match_client.py --engine-threads 1 --engine "py tools/bot_match_example_engine.py"' -WorkingDirectory $PWD -WindowStyle Minimized10. Passer à votre propre moteur
Après le test avec le moteur d’entraînement, passez à votre moteur : options dédiées ci-dessous pour Edax ou Egaroucid, --nboard pour les autres moteurs compatibles, JSON pour votre moteur personnel. Gardez le même jeton.
- Edax: --edax
- Egaroucid: --egaroucid
- Moteurs NBoard comme NTest : --nboard
- Moteur fait maison : connexion par JSON
Ne cochez une variante (Anti, 10x10, Octagon, Reversi classique) dans Jeux pris en charge que si votre moteur en connaît les règles. Les autres bots et les joueurs peuvent défier votre bot dans chaque jeu coché. Pour modifier ce choix, ouvrez Gérer dans la liste des bots, modifiez Jeux pris en charge et appuyez sur Enregistrer. Ce n'est pas possible pendant une partie en cours ou quand un défi est en attente.
Problèmes fréquents
| Symptôme | Cause et solution |
|---|---|
| Le bot affiche un point gris (hors ligne). | Vérifiez que la fenêtre du connecteur tourne toujours. Il s'arrête si vous fermez la fenêtre, appuyez sur Ctrl+C ou si l'ordinateur se met en veille. |
Un message indique que la commande est introuvable.command not found / is not recognized | Python n'est pas installé, ou la fenêtre n'a pas été rouverte après l'installation. Consultez l'étape 5, ouvrez une nouvelle fenêtre et recommencez à l'étape 4. |
Un message indique que le fichier ne peut pas être ouvert.can't open file | Vous avez lancé la commande hors du dossier du bot. Placez-vous dans le dossier du bot comme à l'étape 4 et vérifiez avec ls que README.md et tools sont listés. |
Un message indique que le jeton est absent, puis le programme s'arrête.FS_BOT_TOKEN is missing or invalid | Cette fenêtre n'a pas de jeton. Si vous avez ouvert une nouvelle fenêtre, refaites l'étape 6. |
Un message indique que le jeton a été refusé, puis le programme s'arrête.Bot credential rejected | Le jeton a été mal collé ou il est ancien. Après la création d'un nouveau jeton ou la désactivation du bot, l'ancien jeton ne fonctionne plus. Recommencez à l'étape 6 avec le jeton le plus récent. |
La même ligne d'erreur revient sans cesse.Connection/state error | Vérifiez la connexion Internet. Sous macOS, vérifiez que vous avez exécuté Install Certificates.command à l'étape 5. Si elle n'apparaît que pendant les parties, le serveur refuse peut-être le coup de votre moteur parce qu'il est illégal. Le connecteur renvoie le même coup, il faut donc corriger le moteur. |
| Le bouton de défi ne fonctionne pas, ou le défi n'est pas accepté. | Sélectionnez Mon bot joueur et vérifiez que les deux bots sont en ligne. L’adversaire doit accepter les défis directs et avoir une place libre. Un défi sans réponse expire après 120 secondes. |
Le bot ne joue aucun coup, puis perd au temps ou la partie est annulée.Engine failed for match | Le moteur n'a pas répondu à temps ou sa réponse n'avait pas le bon format. Vérifiez la commande du moteur et sa sortie JSON sur une ligne. Si un bot ne joue pas de premier coup dans les 30 secondes après le début, la partie est annulée. |
| Aucun défi en variante n'arrive. | La fenêtre de défi ne liste que les jeux pris en charge par les deux bots. Vérifiez que le jeu est coché dans Jeux pris en charge de votre bot et que l'autre bot le prend aussi en charge. Un bot connecté par --edax ou --nboard ne doit avoir que Standard coché. |
Glossaire
| Terme | Signification |
|---|---|
| API | Une manière convenue pour les programmes d'envoyer des demandes et des réponses. Le connecteur s'en charge pour vous. |
| Jeton | Un mot de passe propre à votre bot. Le connecteur s'en sert pour prouver au serveur de quel bot il s'agit. |
| Terminal | Une fenêtre où l'on tape des commandes. Sous Windows, utilisez PowerShell. |
| Variable d'environnement | Un réglage temporaire transmis aux programmes lancés depuis une fenêtre de terminal. Il disparaît quand la fenêtre se ferme. |
| JSON | Un format pour écrire des données sous forme de texte. Exemple : {"move":19} |
| Moteur | Un programme qui examine une position et choisit un coup. |
| Adaptateur | Un petit programme qui convertit les données entre votre moteur et le connecteur. |
| NBoard | Un format ouvert que les moteurs d'Othello et les programmes de plateau utilisent pour échanger positions et coups. Les moteurs qui le prennent en charge, comme NTest, se connectent sans adaptateur. |
| Coup légal | Une case où vous pouvez jouer maintenant. Le serveur les liste dans legal_moves. |
Connecter votre moteur
Utilisez au maximum 4 threads par moteur. Un match de bots comprend deux parties simultanées, soit au maximum 8 threads au total.
Edax: --edax
Les exemples d’installation et de lancement ci-dessous utilisent Edax 4.6 et Egaroucid for Console 7.8.2.
Edax 4.6 n’est pas inclus dans le programme de connexion. Téléchargez le fichier adapté à votre système dans Assets sur Edax 4.6, placez-le dans le dossier du bot et extrayez-le avec les commandes de préparation ci-dessous. Les commandes Windows et Linux visent les ordinateurs x86-64.
Windows PowerShell (x86-64): edax-4.6-MS-windows-x86.zip
Préparer (la première fois seulement)
Expand-Archive -LiteralPath edax-4.6-MS-windows-x86.zip -DestinationPath edax-4.6Lancer
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
Préparer (la première fois seulement)
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-64Lancer
python3 tools/bot_match_client.py --engine-threads 2 --edax "edax-4.6/lEdax-x86-64"macOS: edax-reversi-4.6.tar.gz
Il n’existe pas d’exécutable macOS officiel pour Edax 4.6. Téléchargez Source code (tar.gz) et edax-4.6-linux-x86.tar.gz depuis cette version. Compilez le programme Mac à partir des sources ; seule la donnée commune data/eval.dat est extraite de l’archive Linux. Les outils de ligne de commande Xcode sont nécessaires. Les commandes de préparation compilent les sources.
Préparer (la première fois seulement)
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)Lancer
python3 tools/bot_match_client.py --engine-threads 2 --edax "edax-4.6/bin/mEdax-native"Edax peut aussi se connecter en indiquant uniquement son exécutable avec --edax ci-dessous. Aucun adaptateur séparé n’est nécessaire. Le connecteur lance Edax en xboard et envoie les deux temps restants avant chaque coup ; Edax décide lui-même de son temps de réflexion d’après sa pendule (connecteur v1.4.8 ou plus récent). Pendant la partie, Edax garde son historique et sa table de hachage, et avec --engine-ponder on il cherche aussi pendant le temps de l’adversaire. --edax-protocol nboard conserve l’ancienne connexion NBoard.
Remplacez le chemin de la commande par le chemin complet de votre exécutable. Encadrez les chemins contenant des espaces de guillemets doubles. Si le fichier d’évaluation est introuvable, indiquez eval.dat avec --edax-eval.
Une connexion par --edax ou --nboard ne joue que des parties standard en 8×8. Pour ce bot, ne laissez que Standard coché dans Jeux pris en charge. Si une variante arrive, le connecteur n'interroge pas le moteur, aucun coup n'est joué, et la partie est annulée ou perdue au temps.
Egaroucid: --egaroucid
Préparez Egaroucid for Console. Choisissez l’exécutable console et laissez le dossier resources à sa place. Sur macOS et Linux, utilisez un exécutable compilé selon les instructions officielles. Les commandes natives setboard, settime et go transmettent la position et le temps restant, sans adaptateur.
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"Ces deux modes prennent uniquement en charge le jeu standard 8×8, avec un moteur par partie simultanée. --max-think-seconds est la limite de sécurité par coup (10 secondes par défaut). Si Egaroucid l’atteint, le connecteur arrête la recherche, joue un coup légal de secours et relance le moteur au tour suivant.
Moteurs NBoard comme NTest : --nboard
NBoard est une interface graphique d’Othello utilisable avec NTest. Le protocole NBoard est son format public de communication avec les moteurs ; connectez les moteurs qui le prennent en charge, comme NTest, avec --nboard. Un moteur par partie reste ouvert. Edax le prend aussi en charge, mais connectez Edax avec --edax ci-dessus.
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"Une connexion par --edax ou --nboard ne joue que des parties standard en 8×8. Pour ce bot, ne laissez que Standard coché dans Jeux pris en charge. Si une variante arrive, le connecteur n'interroge pas le moteur, aucun coup n'est joué, et la partie est annulée ou perdue au temps.
Moteur fait maison : connexion par JSON
Ne lisez cette partie que si vous voulez connecter un moteur que vous avez écrit vous-même. Si vous utilisez Edax, Egaroucid ou un moteur NBoard, vous avez déjà terminé plus haut et vous pouvez la passer.
Chaque fois que c'est au tour de votre bot, le connecteur lance my_adapter.py une fois. Il lui transmet la position actuelle sur une ligne (où sont les pions, à qui c'est le tour, quelles cases sont légales, combien de temps il reste), my_adapter.py répond par une case sur une ligne, et le connecteur joue ce coup sur le serveur. my_adapter.py est un petit fichier Python placé entre les deux, qui demande le coup à votre moteur. Le connecteur s'occupe de la connexion au serveur, du jeton et de l'envoi des coups. Ce fichier n'a donc jamais à s'en charger.
bot_match_client.py→ my_adapter.pybot_match_client.py← my_adapter.pyDe quel type est votre moteur ?
- Un moteur qui choisit son coup dans du code Python : utilisez l'exemple A ci-dessous.
- Un fichier programme qui affiche une ligne de réponse puis se ferme à chaque lancement : utilisez l'exemple B ci-dessous.
- Un exécutable qui reste ouvert et échange des commandes en continu : s'il prend en charge NBoard, connectez-le avec --nboard ci-dessus. Pour un autre protocole, adaptez l'exemple B à ce protocole et faites en sorte que my_adapter.py garde le moteur ouvert et échange une ligne à la fois en boucle.
Étape 1 : un fichier qui vérifie seulement la connexion (my_adapter.py)
Dans le dossier du bot (là où se trouvent README.md et tools), créez un fichier nommé my_adapter.py, collez-y le code ci-dessous tel quel et enregistrez-le. Ce fichier n'utilise aucun moteur et répond simplement par la première case légale. Il sert à vérifier que la connexion fonctionne avant de brancher votre moteur.
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)
Vérifier l'entrée et la sortie avant de connecter
La commande du bloc 1 envoie directement la position d'exemple à l'adaptateur. Elle doit afficher une ligne : {"move": 19}. Une fois cette ligne affichée, lancez avec la commande du bloc 2 le connecteur avec cet adaptateur, dans la fenêtre qui contient le jeton de l'étape 6. Exécutez les deux blocs séparément. Si votre moteur lit lui-même ce format JSON, vous pouvez mettre sa commande directement après --engine.
1. Tester l'adaptateur seul
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. Lancer le connecteur avec l'adaptateur
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'Étape 2 : passer à un fichier qui appelle votre moteur
Une fois que l'étape 1 fonctionne, remplacez tout le contenu de my_adapter.py par l'exemple A ou B ci-dessous. Modifiez seulement les lignes marquées EDIT et laissez le reste tel quel. Relancez ensuite la commande de test 1 ci-dessus et vérifiez qu'une ligne de réponse s'affiche. C'est votre moteur qui a choisi le coup, il est donc normal d'obtenir une autre case que 19.
Exemple A : un moteur qui choisit son coup avec une fonction Python
Cet exemple suppose un fichier nommé my_engine.py contenant une fonction search qui choisit le coup. À EDIT 1, changez le nom du fichier et celui de la fonction, et à EDIT 2, changez les valeurs transmises, pour qu'ils correspondent à votre moteur. La fonction doit renvoyer le numéro de la case (0 à 63) ou une coordonnée comme 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)Exemple B : un moteur sous forme de fichier programme
Cet exemple suppose que le programme lit une ligne contenant 64 caractères du plateau, le camp qui doit jouer et le temps de réflexion en millisecondes, puis répond par une ligne de coordonnée comme D3 (. = vide, X = noir, O = blanc). Chaque moteur a son propre format. Changez donc le nom du fichier programme à EDIT 1, la ligne envoyée au moteur à EDIT 2 et la partie qui lit la réponse à EDIT 3 pour les adapter à votre moteur.
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)Temps de réflexion : dans les parties entre bots, chaque bot dispose de 1 minute par partie, donc réfléchir longtemps sur un seul coup fait vite perdre au temps. Dans les exemples, think_ms divise le temps restant (remaining_ms) par le nombre de coups qu'il vous reste à jouer pour fixer le temps de ce coup. budget_ms n'est pas le temps à consacrer à ce coup. C'est le temps maximal pendant lequel le connecteur attend la réponse (10 secondes par défaut). Si la réponse arrive plus tard, le bot ne peut pas continuer cette partie et la perd au temps. Transmettez donc think_ms à votre moteur, et non budget_ms.
En cas de problème : si l'appel du moteur échoue, les fichiers d'exemple écrivent la raison dans my_adapter.log et jouent la première case légale à la place. Si les coups vous semblent bizarres, ouvrez d'abord ce fichier. Le connecteur n'affiche pas à l'écran les messages d'erreur de l'adaptateur. N'utilisez print que pour la ligne de réponse et écrivez tout texte de débogage dans un fichier.
Vitesse : le connecteur garde my_adapter.py ouvert pour chaque partie et envoie une ligne par coup. Un fichier qui répond une ligne puis se termine, comme les exemples, est relancé au coup suivant ; votre moteur redémarre donc à chaque fois. Si le moteur démarre lentement ou doit garder le travail des coups précédents, faites de my_adapter.py une boucle : lire une ligne, répondre une ligne, recommencer. Ne lisez pas l'entrée jusqu'au bout et faites un flush après chaque réponse.
Le reste de cette partie est une documentation de référence sur ce que le connecteur et my_adapter.py échangent. Si vous utilisez les fichiers d'exemple ci-dessus tels quels, vous n'avez pas besoin de la lire.
JSON reçu (connecteur → adaptateur)
Il s’agit de données envoyées par le connecteur, pas de code exécutable. Ne les enregistrez pas dans un fichier Python. Pendant une partie, le connecteur transmet automatiquement les données à chaque tour.
Voici un exemple avec la position de départ standard en 8×8. Dans les vraies parties, le connecteur remplit la position actuelle. board liste les cases à partir de a1 vers la droite, puis la rangée suivante ; 0=vide, 1=noir, 2=blanc. color=1 demande un coup des noirs. legal_moves liste les cases où vous pouvez jouer. remaining_ms est le temps restant à la pendule pour la partie et budget_ms le temps maximal pendant lequel le connecteur attend la réponse pour ce coup, tous deux en millisecondes (1000 = 1 seconde). Les champs et exemples des variantes se trouvent plus bas, dans la section sur les variantes.
{"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 de réponse (adaptateur → connecteur)
Écrivez l'une des réponses ci-dessous sur une seule ligne JSON terminée par un saut de ligne. move est un numéro de case ou une coordonnée, sans distinction de majuscules. En 8×8, d3 vaut (3−1)×8+3 = 19. Choisissez toujours parmi les legal_moves reçus. Dans les paires de bots, s'il n'y a aucun coup légal, envoyez -1 ou pass ; dans les parties contre un humain, le serveur gère les passes forcées. N'écrivez que la ligne de réponse sur stdout, sans aucun autre message.
{"move":19}{"move":"d3"}{"move":-1}Facultatif : ajoutez environment à la réponse pour signaler le nombre réel de threads, la taille de hachage en MB et le ponder du moteur (connecteur v1.4.6 ou plus récent). Le connecteur n’accepte que des nombres dans la plage et true/false et les affiche dans les informations du bot. Si votre adaptateur ajoute eval, le connecteur l’envoie avec le coup dans les matchs entre bots (par exemple {"move":19,"eval":1.5}). eval est votre évaluation après le coup, en pions de votre point de vue et au plus le nombre de cases jouables ; --edax, --egaroucid et les moteurs NBoard l’envoient d’eux-mêmes après la mise à jour vers v1.5.3.
{"move":19,"environment":{"engine_threads":1,"hash_mb":32,"ponder":false}}Téléchargements
Télécharger les exemples Python
GitHub: flipsight-othello-bot-connector
Le .zip contient le guide, le connecteur et le moteur exemple ; le .json est la spécification API et le .md le guide.
Implémenter l'API vous-même
Arrêtez d’abord le connecteur d’entraînement. Ouvrez le flux avec le jeton de l’étape 6. Gardez une connexion par jeton. Chaque ligne contient un événement JSON.
Flux d’événements
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"Après hello, vous recevez state. Cet exemple montre les champs utiles pour votre bot numéro 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]
}
]
}
}
]
}Votre bot joue les noirs (1) sur le deuxième plateau (leg 1). Comme turn vaut 1, choisissez un coup dans legal_moves et envoyez-le avec la revision de ce plateau. Pour jouer, configurez le jeton dans un second terminal comme à l’étape 6 et utilisez les valeurs de la partie en cours.
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}'Flux d’événements
| Type | Description |
|---|---|
hello | Connexion établie. bot_id identifie votre bot. |
state | Remplacez la liste des parties en cours et des invitations. Si vous êtes bot_b, agent_accept permet d’accepter une invitation pending. |
match | Mettez à jour la partie portant cet id. Vérifiez sur chaque plateau actif si votre bot a le trait. |
ping | Signal de présence toutes les 10 secondes. Aucune réponse attendue. |
closing | Dernière ligne avant que le serveur ferme le flux. Si reason vaut overflow (trop de lignes non envoyées) ou server_shutdown, reconnectez-vous et rattrapez l’état avec state. replaced signifie que le même jeton est utilisé ailleurs. Ne vous reconnectez pas tout de suite : attendez au moins 30 secondes, et plus longtemps si cela se répète. N’utilisez chaque jeton qu’à un seul endroit. |
Objet match (matches[])
| Champ | Type | Description |
|---|---|---|
id | integer | ID du match (négatif pour les parties contre un humain) |
kind | string | human pour les parties contre un humain |
bot_a | integer | ID du bot du participant 0 (0 pour un humain) |
bot_b | integer | ID du bot du participant 1 (0 pour un humain) |
game_mode | string | Jeu (std, anti, grand, octagon, reversi) |
time_limit_sec | integer | Secondes accordées par partie et par couleur |
status | string | pending, running, finished, aborted, rejected, expired |
expires_ms | integer | Date limite d’acceptation (millisecondes) |
ranked | boolean | Indique si le match est classé |
state.status | string | active, finished ou aborted |
state.game_mode | string | Jeu (std, anti, grand, octagon, reversi) |
state.board_size | integer 8 | 10 | Cases par côté, 8 ou 10 |
state.blocked_squares | integer[] | Cases inutilisables (Octagon uniquement, non triées) |
state.legs | array | Parties (2 entre bots, 1 contre un humain) |
state.totals | [integer, integer] | Total des pions des deux parties par participant |
state.winner | integer | null | Participant gagnant 0 ou 1, null en cas de nulle |
state.finish_reason | string | null | discs, timeout, double_timeout, disconnect, no_first_move |
Objet partie (state.legs[])
| Champ | Type | Description |
|---|---|---|
board | integer[64 | 100] | 64 / 100 cases, 0=vide 1=noir 2=blanc |
turn | integer | Couleur au trait, 1 (noir) ou 2 (blanc) |
legal_moves | integer[] | Cases légales pour la couleur au trait. Vide pour les parties terminées |
placed | {"1": integer, "2": integer} | Pions posés par couleur, clés "1" (noirs) et "2" (blancs) |
black_participant | integer | Participant qui a les noirs dans cette partie |
clocks_ms | [number, number] | Bases de temps restant dans l’ordre des couleurs (noir, blanc) |
turn_started_ms | integer | Heure du serveur au début du tour en cours |
revision | integer | Augmente de 1 à chaque changement de cette partie |
status | string | active, finished, timeout, stopped |
history | array | Coups joués (color, participant, move, at_ms, eval) |
discs | [integer, integer] | Nombre de pions dans l’ordre des couleurs (noir, blanc) |
result_discs | [integer, integer] (optional) | Score arbitré facultatif [noirs, blancs] pour une partie perdue au temps ; il est totalisé à la place des pions. Scores pour le camp qui a dépassé le temps et son adversaire : std et reversi 0 à 64, grand 0 à 100, octagon 0 à 88, anti 64 à 0. L'autre partie continue, et les totaux désignent le vainqueur une fois les deux parties terminées. Les anciens résultats terminés ne sont pas recalculés. |
Quand une partie se termine, le dernier événement match contient aussi record, l’enregistrement de partie. Sauvegardez-le tel quel pour conserver toute la partie. Enregistrements de parties
Synchronisation
Après une coupure ou 15 secondes sans événement, reconnectez-vous en espaçant les tentatives de 1 à 30 secondes. Ignorez les états anciens. Contre une personne, comparez dans l’ordre room_created_at, round_no et revision. Si la réponse à un coup se perd, renvoyez-le uniquement si le trait et la revision du plateau sont inchangés.
Envoyez les informations du moteur avec agent_environment au démarrage et à chaque modification. Pour l’appariement automatique, la v2 admet au plus 10 connexions au flux et aucun appel à agent_poll sur les 10 dernières minutes en ligne.
Authentification
Utilisez HTTPS, JSON POST et Authorization: Bearer. Le jeton appartient à un seul bot. Ne le placez jamais dans une URL, du code public ou des journaux.
Content-Type: application/json
Authorization: Bearer <FS_BOT_TOKEN>POST https://othelloclub.com/flipsight/bot_match_api.php
Options du connecteur
Options de tools/bot_match_client.py. Il faut exactement une option parmi --engine et --nboard / --edax / --egaroucid. Le jeton n'est jamais une option ; il est lu uniquement dans la variable d'environnement FS_BOT_TOKEN. Codes de sortie : 0 arrêt normal, 2 jeton refusé, 3 --max-runtime atteint.
| Paramètres | Description |
|---|---|
--engine "COMMAND" | Lance cette commande une fois par partie et échange une ligne JSON par coup sans fermer son entrée. Un moteur qui répond une ligne puis se termine est relancé au coup suivant. |
--nboard "COMMAND" | Garde un moteur NBoard par partie, deux au total. Standard (std) uniquement. |
--edax PATH | Edax peut aussi se connecter en indiquant uniquement son exécutable avec --edax ci-dessous. Aucun adaptateur séparé n’est nécessaire. Le connecteur lance Edax en xboard et envoie les deux temps restants avant chaque coup ; Edax décide lui-même de son temps de réflexion d’après sa pendule (connecteur v1.4.8 ou plus récent). Pendant la partie, Edax garde son historique et sa table de hachage, et avec --engine-ponder on il cherche aussi pendant le temps de l’adversaire. --edax-protocol nboard conserve l’ancienne connexion NBoard. |
--edax-eval PATH | Chemin du fichier Edax eval.dat. Par défaut, recherche data/eval.dat dans le dossier de l’exécutable ou son parent. |
--edax-protocol xboard|nboard | Mode de connexion de --edax. Par défaut, xboard laisse Edax gérer sa propre pendule et faire du ponder (v1.4.8 ou plus récent). nboard est la connexion utilisée jusqu’à v1.4.7 : le connecteur fixe le temps de chaque coup et Edax ne fait pas de ponder. |
--egaroucid PATH | Préparez Egaroucid for Console. Choisissez l’exécutable console et laissez le dossier resources à sa place. Sur macOS et Linux, utilisez un exécutable compilé selon les instructions officielles. Les commandes natives setboard, settime et go transmettent la position et le temps restant, sans adaptateur. |
--egaroucid-level N | S'utilise avec --egaroucid. De 1 à 60, Egaroucid démarre à ce niveau (-level N) et ne reçoit pas le temps restant (settime) ; 0 ou sans valeur garde le mode temps, qui suit la pendule. Le mode niveau n'a pas de commande pour arrêter une recherche en cours : si un coup dépasse la limite --max-think-seconds, le connecteur arrête le moteur et joue un coup légal de secours. Choisissez un niveau qui se termine largement dans le temps de la partie. |
--nboard-depth N | Envoie set depth N au moteur NBoard. 0 à 60 ; 0 conserve la valeur par défaut du moteur. Avec --edax, c'est le niveau d'Edax (20 signifie L20) ; sans valeur, le niveau est 60. Edax joue le meilleur coup trouvé dès qu'il atteint le niveau ou que le temps du coup est écoulé, selon ce qui arrive en premier. Avec --edax, la valeur est envoyée en xboard sous la forme sd N. |
--max-think-seconds S | Nombre maximal de secondes d'attente du moteur par coup. Par défaut 10, maximum 300. Jamais plus que le temps restant à la pendule moins 0,75 seconde. C'est une limite de sécurité du connecteur ; le serveur n'impose pas de limite de temps par coup. Avec 0, la limite par coup est supprimée ; le temps de partie restant s’applique. La pendule de la partie est fixée par le site et le connecteur ne peut pas la changer : les parties entre bots et les parties automatiques donnent 60 secondes à chaque couleur par plateau, et une personne qui défie directement votre bot choisit la cadence. Avec --edax, Edax fixe le temps de chaque coup d’après sa propre pendule, dans cette limite ; si la limite est atteinte, le connecteur fait jouer immédiatement à Edax le meilleur coup trouvé. |
--engine-name NAME | Nom du moteur indiqué dans les informations du bot (120 caractères au maximum). N'y mettez ni commande ni chemin. |
--engine-threads N | Nombre de threads utilisés par le moteur par partie , affiché dans le profil. Avec --edax ou --egaroucid, le moteur tourne avec cette valeur (par défaut 4 si l’ordinateur a plus de 4 processeurs logiques, sinon 1) ; avec --engine, elle est envoyée dans chaque requête sous engine_threads. Utilisez au maximum 4 threads par moteur, soit 8 au total par match de bots comprenant deux parties simultanées. Avec --engine/--nboard, une saisie est demandée si cette option manque ; elle est obligatoire en arrière-plan ou sans interaction. |
--engine-hash-mb MB | Taille de la table de hachage par moteur, en MB. Avec --edax ou --egaroucid, la table est réglée sur la plus grande puissance de deux ne dépassant pas cette valeur (Edax -h, Egaroucid -hash) et cette taille est signalée ; sans l’option, Edax utilise edax.ini et Egaroucid 32 MB. Les autres moteurs signalent seulement la valeur et leur réglage ne change pas. Chaque moteur a sa propre table : une partie entre bots jouant deux parties à la fois en utilise le double. |
--engine-ponder on|off | Ponder (recherche pendant le temps de l’adversaire). Avec --egaroucid, on lance Egaroucid avec -ponder et signale Activé ; le CPU est aussi utilisé pendant le tour de l’adversaire. Avec --edax (connecteur v1.4.8 ou plus récent), on fait faire du ponder à Edax par xboard (hard) et signale Activé ; avec --edax-protocol nboard, Edax ne fait pas de ponder et on est refusé. Les autres moteurs signalent seulement leur réglage réel. |
--cpu-name NAME | Nom du processeur à indiquer (120 caractères au maximum). Détecté automatiquement s'il est omis. |
--once-match ID | Ne traite que ce match et s'arrête à sa fin (terminé, annulé, expiré, refusé). Les identifiants négatifs des parties contre un humain fonctionnent aussi. Pour les tests, combinez-la avec --max-runtime. |
--max-runtime S | Arrête proprement les moteurs et quitte après ce nombre de secondes (code de sortie 3). |
--save-games DIR | Conserve chaque partie terminée après l’activation dans DIR/games-YYYY-MM.ndjson, un enregistrement de partie par ligne (désactivé par défaut). Les parties terminées pendant que le connecteur était arrêté ou que le flux était coupé sont complétées avec agent_games à la reconnexion, à partir de la partie sauvegardée la plus récente. Une partie occupe environ 4 Ko (environ 6 Ko en 10×10), donc 1 400 parties par jour font environ 6 Mo par jour et 180 Mo par mois. Supprimez vous-même les anciens fichiers mensuels dont vous n’avez plus besoin. |
--timing-log PATH | Ajoute une ligne par coup indiquant où le temps est passé (réception du coup, attente d'une recherche libre, moteur, envoi du coup). Désactivé par défaut ; rien de plus n'est envoyé au serveur. |
--api URL, --stream-url URL | Adresses de l'API et du flux. Gardez normalement les valeurs par défaut. Seul HTTPS est accepté et, comme le jeton est envoyé avec, le flux doit être sur l'hôte de l'API. |
Variantes
Un bot ne reçoit que les jeux cochés dans Jeux pris en charge. Le game_mode des requêtes au moteur et de l'état du match indique le jeu. Le serveur calcule la taille du plateau, les cases bloquées et les cases légales, le moteur n'a donc qu'à choisir parmi les legal_moves reçus. Ne générez pas les coups du 10×10 ou du Reversi classique avec la génération de coups du 8×8 standard.
| Jeu | game_mode | Plateau |
|---|---|---|
| Standard | std | 8×8 |
| Anti | anti | 8×8 |
| Grand (10x10) | grand | 10×10 |
| Octagon | octagon | 10×10 (88) |
| Reversi classique | reversi | 8×8 |
Règles communes : les noirs (1) jouent en premier. Les deux parties partent de la même position avec les couleurs inversées et se jouent en même temps. Dans les paires de bots, quand vous n'avez aucun coup légal, legal_moves arrive sous forme de tableau vide et le bot doit envoyer lui-même move=-1 (passe). Le serveur ne passe pas à votre place, et votre pendule continue de tourner. Passer alors qu'un coup légal existe est illégal. Une partie se termine quand aucune couleur ne peut jouer. Dans les nouveaux matchs doubles, les cases vides de chaque partie terminée normalement sont ajoutées à la couleur ayant le plus de pions, puis les deux scores sont additionnés. En Anti, le total corrigé le plus faible gagne ; à égalité de pions, aucune case vide n’est attribuée. Des totaux égaux donnent une partie nulle. Toutes les parties entre bots commencent dans une position aléatoire avec 12 pions. Pour chaque variante, chaque bot dispose de 1 minute par partie.
Anti : la pose et le retournement des pions fonctionnent comme à l'Othello standard. Le camp qui a le moins de pions sur les deux parties gagne.
10x10 : règles standard sur un plateau 10×10 (100 cases). Les pions de départ occupent les quatre cases centrales ; les paires de bots ajoutent 8 coups aléatoires et commencent à 12 pions.
Octagon : même plateau et même position de départ que le 10x10, mais trois cases dans chaque coin, 12 au total, sont inutilisables (88 cases jouables). Les cases bloquées arrivent sous forme de numéros de case dans blocked_squares et sous forme de 0, la même valeur que vide, dans board. Le tableau n'est pas trié par ordre numérique. On ne peut pas jouer sur une case bloquée, et les lignes de pions s'y arrêtent.
Reversi classique : selon ses règles, la partie commence sur un plateau vide. Tant que l'une des quatre cases centrales (27, 28, 35, 36) est vide, on ne pose que là et rien n'est retourné. Une fois les quatre remplies, les règles standard s'appliquent. Chaque couleur pose au plus 32 pions, y compris les quatre premiers coups. placed compte les pions posés jusqu'ici par chaque couleur ; ses clés sont les chaînes "1" (noirs) et "2" (blancs). Les paires de bots commencent après que le serveur a posé 12 pions au hasard, dont les quatre coups au centre ; dans la première requête, les deux valeurs de placed totalisent donc 12 (en général {"1":6,"2":6}). Une couleur qui a posé ses 32 pions reçoit un legal_moves vide et envoie -1 à chacun de ses tours.
Exemples de requêtes au moteur par jeu
Exemples de la première requête pour les noirs que le connecteur envoie à un moteur lancé avec --engine, générés avec le code des règles. Les vraies parties de tous les types partent d'une position aléatoire à 12 pions, donc board et legal_moves diffèrent à chaque partie. Pour que ces exemples restent fixes, leurs premiers coups ont été choisis près du centre du plateau. match_id et les valeurs de pendule diffèrent aussi dans les vraies parties.
Anti (anti)
JSON reçu (connecteur → adaptateur)
{
"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 de réponse (adaptateur → connecteur)
{"move":2}Grand (10x10) (grand)
JSON reçu (connecteur → adaptateur)
{
"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 de réponse (adaptateur → connecteur)
{"move":13}Octagon (octagon)
JSON reçu (connecteur → adaptateur)
{
"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 de réponse (adaptateur → connecteur)
{"move":13}Reversi classique (reversi)
JSON reçu (connecteur → adaptateur)
{
"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 de réponse (adaptateur → connecteur)
{"move":18}Champs de la requête au moteur
| Champ | Type | Description |
|---|---|---|
game_mode | string | L'une des valeurs std, anti, grand, octagon, reversi. Le XOT des parties contre un humain arrive comme std. |
board_size | integer 8 | 10 | 8, ou 10 pour grand et octagon. |
board | integer[board_size²] | Tableau de longueur board_size². Se lit à partir de a1 vers la droite, puis la rangée suivante. 0=vide (y compris les cases bloquées de l'Octagon), 1=noir, 2=blanc. |
blocked_squares | integer[] | Cases inutilisables de l'Octagon. Tableau vide dans les autres jeux. |
placed | {"1": integer, "2": integer} | Pions posés jusqu'ici par couleur, y compris les coups d'ouverture aléatoires ; les clés sont les chaînes "1" et "2". Sert à la limite de 32 pions du Reversi classique. |
legal_moves | integer[] | Cases où vous pouvez jouer maintenant. Si la liste est vide, répondez move=-1. |
color | integer 1 | 2 | Couleur au trait. 1=noir, 2=blanc. |
budget_ms | integer | Temps accordé pour ce coup en millisecondes : la plus petite valeur entre --max-think-seconds et le temps restant à la pendule moins 0,75 seconde. Le connecteur arrête le moteur en cas de dépassement. |
remaining_ms | integer | Temps restant de votre couleur dans cette partie, en millisecondes, après déduction du temps déjà utilisé pendant ce tour. |
match_id | integer ≠ 0 | Identifiant du match. Négatif (-numéro de salle) pour les parties contre un humain. |
leg | integer 0 | 1 | Numéro de partie 0 ou 1. Toujours 0 pour les parties contre un humain. |
revision | integer | Numéro d'état de cette partie. Renvoyez-le tel quel avec agent_move. |
history | array | Coups joués dans cette partie. Décidez à partir de board. |
round_no | integer | null | Numéro de ronde d'une partie contre un humain. null pour les paires de bots. |
room_created_at | string | null | Heure de création de la salle d'une partie contre un humain. null pour les paires de bots. |
engine_threads | integer (optional) | Présent seulement si le programme de connexion a été lancé avec --engine-threads. Nombre de threads que le moteur peut utiliser pour cette partie ; dimensionnez la recherche en conséquence. |
Défier un autre bot dans une variante
Ajoutez game_mode à agent_challenge ; la valeur par défaut est std. Les deux bots doivent l'avoir dans supported_games. Consultez les jeux de l'adversaire sur la page des bots. Si l'un des bots ne propose pas ce jeu, la réponse est HTTP 409 avec l'erreur ci-dessous.
{"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}Modifier supported_games
Le formulaire d'enregistrement commence avec Standard coché, et les anciens bots sans liste enregistrée prennent en charge std. La liste ne peut être modifiée que dans Gérer sur la page web des bots, jamais avec le jeton du bot (API). La modification est refusée pendant un match en cours ou en attente d'acceptation. Une liste vide ne peut pas être enregistrée.
Humains contre bots enregistrés
Les joueurs peuvent défier votre bot dans n'importe quel jeu enregistré pour lui. S'il prend en charge le standard, des parties STD comme XOT peuvent arriver. Le XOT arrive avec game_mode std et part d'un plateau où 8 coups ont déjà été joués (ils figurent dans history). La personne qui défie choisit la pendule, et la partie n'est pas classée. Un match contre un humain comporte une seule partie (leg 0) et un match_id négatif. Le serveur gère les passes quand aucun coup n'est possible, n'envoyez donc pas -1. Les bots inscrits en ligne dont l’appariement automatique est activé participent aussi aux parties rapides STD/XOT compatibles. Elles sont classées pour les membres et non classées pour les invités.
Coups illégaux et temps
Un coup illégal ou une revision périmée est refusé avec HTTP 409 (illegal_move, stale_revision, not_your_turn) et le plateau ne change pas. La pendule continue de tourner pendant ce temps. Le connecteur renvoie le même coup avec la même revision, donc si le moteur n'est pas corrigé, cette partie finit par être perdue au temps. Le serveur n'a pas de limite par coup et ne vérifie que le temps restant de chaque couleur. Les 10 secondes sont la valeur par défaut de --max-think-seconds du connecteur.
Règles du match
Toutes les parties entre bots commencent dans une position aléatoire avec 12 pions. Deux parties se jouent simultanément en inversant les couleurs. Le total des pions détermine le vainqueur ; le plus petit total gagne en Anti.
Pour chaque variante, chaque bot dispose de 1 minute par partie.
Si un bot n’a pas joué son premier coup dans les 30 secondes suivant le début, le match est annulé et non classé. Si, pendant le match, la connexion d’un bot est perdue plus de 30 secondes alors que l’autre est connecté, le bot connecté gagne (finish_reason: disconnect) et le résultat est classé.
Le serveur calcule les coups des bots FlipSight dans tous les types de jeu. Les défis web et les défis par l'API (agent_challenge) sont acceptés, et le serveur lance le match aussitôt : inutile de garder la salle de jeu ouverte. Si le calcul du serveur s'arrête plus de 30 secondes, le match est annulé (finish_reason: technical) et n'est pas classé. Les variantes coûtent cher à calculer : au plus 2 matchs de variante contre des bots FlipSight se jouent à la fois. Quand tout est pris, vous recevez HTTP 409 avec site bot variant matches are full ; réessayez un peu plus tard.
L’appariement automatique réunit des bots à 500 points de classement ou moins dans une variante choisie par les deux. Le connecteur a 120 secondes pour accepter. Le résultat compte pour le classement. Dans Gérer, choisissez les variantes ou désactivez l’appariement automatique. Un bot lancé avec le moteur d'entraînement (environment.practice vaut true) est exclu des matchs automatiques, et ses matchs contre d'autres bots pendant ce temps ne sont pas classés.
Un défi direct humain joue une partie dans une salle normale avec un jeu et un temps compatibles. Le serveur impose toujours le mode non classé aux défis directs. Les bots inscrits en ligne dont l’appariement automatique est activé participent aussi aux parties rapides STD/XOT compatibles. Elles sont classées pour les membres et non classées pour les invités. Un bot enregistré n'accepte que le nombre de parties fixé par son réglage de parties simultanées (2 par défaut). Une partie contre un humain et un match entre bots (deux plateaux) comptent chacun pour 1.
Déroulement d’un match
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)Toutes les parties entre bots commencent dans une position aléatoire avec 12 pions. Deux parties se jouent simultanément en inversant les couleurs. Le total des pions détermine le vainqueur ; le plus petit total gagne en Anti.
Votre numéro de participant est 0 si vous êtes bot_a et 1 si vous êtes bot_b. Le participant 0 a les noirs (1) dans legs[0] et les blancs (2) dans legs[1] ; c’est l’inverse pour le participant 1. C’est votre tour quand leg.status vaut active et que leg.turn correspond à votre couleur. Ce peut être votre tour dans les deux parties à la fois.
Si vous n’avez aucun coup légal, vous devez envoyer vous-même move -1 (passe) ; le serveur ne passe pas à votre place. Dans les parties contre un humain, le serveur gère les passes comme dans les salles de jeu normales.
À votre tour, temps restant = clocks_ms[votre couleur - 1] - (server_now_ms - turn_started_ms). clocks_ms suit l’ordre des couleurs (noir, blanc) ; totals et winner suivent l’ordre des participants (winner 0 ou 1, null en cas de nulle).
Numéros de case
Numéro de case = ligne × 8 + colonne, donc a1=0, h1=7, a2=8 et h8=63. Par exemple, 19 est d3 et 37 est f5. Le tableau board suit le même ordre, avec 0=vide, 1=noir, 2=blanc.
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 63En 10×10 (grand, octagon), case = rangée × 10 + colonne. Les colonnes vont de a à j, et la dixième rangée s'écrit 10 ou 0 dans les coordonnées. a1=0, j1=9, a2=10, j10=99 (identique à j0). Une même coordonnée a un numéro différent selon la taille du plateau : d3 vaut 19 en 8×8 et 23 en 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 ## ##Adaptateur moteur
Le connecteur de bot FlipSight (Python 3.9+, bibliothèque standard uniquement) fonctionne sous Windows, macOS et Linux et connecte un moteur de deux façons. --engine lance le moteur une fois par partie, envoie une ligne JSON à chaque coup et lit une ligne {"move": case}. Un moteur qui répond une ligne puis se termine fonctionne toujours, car il est relancé au coup suivant, mais un moteur qui lit l'entrée jusqu'au bout (sys.stdin.read(), etc.) ne répond jamais : lisez une ligne à la fois. legal_moves dans la requête liste les cases légales ; si elle est vide, répondez -1. --nboard garde un moteur NBoard en marche, un par partie ; réglez sa profondeur avec --nboard-depth.
Actions API
Les exemples de réponse montrent le format. Le bouton de copie copie seulement la requête et n’appelle pas l’API.
POST agent_environment
Signaler l’environnement
Signale le CPU, l'OS, le nom du moteur, les threads et le mode entraînement (practice) du PC du connecteur. Envoyez-le au démarrage et quand les valeurs changent. La réponse contient votre bot.
| Paramètres | Type | Obligatoire | Description |
|---|---|---|---|
action | string "agent_environment" | Obligatoire | Nom de l’action à appeler |
environment | object | Obligatoire | CPU, OS et nom du moteur du PC du connecteur (120 caractères max. chacun, facultatif) et practice (true ou false, facultatif). practice à true signifie que le bot s'entraîne : il est exclu des matchs automatiques, et les matchs entre bots demandés ou acceptés pendant ce temps ne sont pas classés. Le connecteur l'envoie tout seul quand il est lancé avec le moteur d'entraînement. Le serveur garde la dernière valeur reçue : à la fin de l'entraînement, envoyez-la sans practice ou avec false. hash_mb (MB): Par moteur. Sans valeur du connecteur, saisissez-la. ponder (true / false / null): Affichage seul. Sans valeur signalée, choisissez manuellement. Réglez le moteur lui-même. |
Exemple de requête
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}}'Exemple de réponse
{
"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
Défier
Indiquez target_id (numéro du bot) ou target_name (nom du bot), affichés sur la page des bots. Les bots FlipSight intégrés (is_builtin: true) peuvent être défiés par l'API dans tous les types de jeu, et le serveur lance le match aussitôt. Si 2 matchs de variante contre des bots intégrés sont déjà ouverts, vous recevez HTTP 409 avec site bot variant matches are full. Si le bot visé a désactivé « Défis de bots » dans la gestion des bots, vous recevez HTTP 409 avec bot does not accept bot challenges. Les parties automatiques entre bots ignorent ce réglage et suivent celui de l'appariement automatique.
Vous pouvez défier le même bot trois fois de suite. Attendez cinq minutes après la fin du troisième match.
Défier depuis la page des bots
| Paramètres | Type | Obligatoire | Description |
|---|---|---|---|
action | string "agent_challenge" | Obligatoire | Nom de l’action à appeler |
target_id | integer ≥ 1 | Facultatif | ID du bot à défier |
target_name | string | Facultatif | Nom du bot à défier (au lieu de target_id) |
game_mode | string std | anti | octagon | grand | reversi | Facultatif | Jeu pour une paire de bots. std par défaut. Les deux bots doivent le prendre en charge. Standard / Anti / Octagon / Grand (10x10) / Reversi classique |
Exemple de requête
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"}'Exemple de réponse
{
"ok": true,
"match_id": 123,
"server_now_ms": 1800000000000
}POST agent_accept
Accepter
| Paramètres | Type | Obligatoire | Description |
|---|---|---|---|
action | string "agent_accept" | Obligatoire | Nom de l’action à appeler |
match_id | integer ≥ 1 | Obligatoire | ID du match (négatif pour les parties contre un humain) |
Exemple de requête
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}'Exemple de réponse
{
"ok": true,
"match": {
"id": 123,
"status": "running",
"bot_a": 1,
"bot_b": 2
},
"server_now_ms": 1800000000000
}POST agent_reject
Refuser
| Paramètres | Type | Obligatoire | Description |
|---|---|---|---|
action | string "agent_reject" | Obligatoire | Nom de l’action à appeler |
match_id | integer ≥ 1 | Obligatoire | ID du match (négatif pour les parties contre un humain) |
Exemple de requête
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}'Exemple de réponse
{
"ok": true,
"match": {
"id": 123,
"status": "rejected",
"bot_a": 1,
"bot_b": 2
},
"server_now_ms": 1800000000000
}POST agent_move
Envoyer un coup
| Paramètres | Type | Obligatoire | Description |
|---|---|---|---|
action | string "agent_move" | Obligatoire | Nom de l’action à appeler |
match_id | integer ≠ 0 | Obligatoire | ID du match (négatif pour les parties contre un humain) |
round_no | integer ≥ 0 | Obligatoire contre une personne | Parties contre un humain uniquement : round_no de l’objet match |
room_created_at | string | Obligatoire contre une personne | Parties contre un humain uniquement : room_created_at de l’objet match |
leg | integer 0 | 1 | Obligatoire | Partie 0 ou 1 (0 pour les parties contre un humain) |
revision | integer ≥ 0 | Obligatoire | revision de la partie pour laquelle le coup a été calculé ; 409 stale_revision si la partie a changé |
move | integer -1..99 | string | Obligatoire | Case 0-(board_size²−1), -1 pour passer / d3 / D3 / pass |
eval | number -100..100 | Facultatif | L’évaluation de votre moteur après ce coup, en pions de votre point de vue (+ signifie que vous menez, 2 décimales gardées). Elle va jusqu’au nombre de cases jouables : de -64 à 64 en 8x8, de -100 à 100 en 10x10 et de -88 à 88 en octogone. Si vous l’omettez ou envoyez une valeur invalide, seule l’évaluation est ignorée et le coup est accepté. Seuls les matchs entre bots la gardent, tout le monde la voit pendant la partie, y compris le bot adverse, et les parties contre un humain l’ignorent. |
Exemple de requête
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}'Humains contre bots enregistrés
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"}'Exemple de réponse
{
"ok": true,
"match": {
"id": 123,
"status": "running",
"bot_a": 1,
"bot_b": 2
},
"server_now_ms": 1800000000000
}POST agent_games
Télécharger les enregistrements de parties
Renvoie les parties terminées de votre bot sous forme d’enregistrements de parties. La réponse est en NDJSON (Content-Type application/x-ndjson), une partie par ligne. Elle inclut les matchs entre bots et les parties contre des humains, mais pas les parties d’entraînement ni les parties contre le compte du site othelloclub. Les annulations techniques sont incluses avec result void.
Cette requête ne fait pas apparaître votre bot en ligne et ne compte pas pour la vérification de la spécification API v2. Chaque bot peut l’appeler une fois toutes les 5 secondes ; un appel plus rapide reçoit 429 avec retry_after_sec. Envoyez Accept-Encoding: gzip pour recevoir une réponse compressée.
| Paramètres | Type | Obligatoire | Description |
|---|---|---|---|
action | string "agent_games" | Obligatoire | Nom de l’action à appeler |
since | integer ≥ 0 | Facultatif | updated_ms le plus ancien à inclure, en ms. Par défaut 0. |
until | integer ≥ 0 | Facultatif | updated_ms le plus récent à inclure, en ms. Par défaut : maintenant. |
max | integer 1..300 | Facultatif | Nombre maximal de parties par réponse, de 1 à 300. Par défaut 100. |
games | array | Facultatif | Jeux à inclure (std, anti, octagon, grand, reversi). Par défaut : tous. |
order | string asc | desc | Facultatif | asc : les plus anciennes d’abord (par défaut). desc : les plus récentes d’abord. |
Exemple de requête
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}'Exemple de réponse
{
"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]
}
]
}Enregistrements de parties
Un enregistrement de partie (record) est un objet JSON pour une partie terminée. Il contient les joueurs, le résultat, les classements, l’ouverture et l’heure de chaque coup, du point de vue de votre bot. Vous recevez le même objet à deux endroits.
- Événement de fin de partie: Quand une partie se termine, le dernier événement match (status finished ou aborted) contient record.
- agent_games: Renvoie les parties terminées, une par ligne. Utilisez-le pour les parties passées et celles que vous avez manquées.
Les coups utilisent la notation de partie du site. Chaque coup fait deux caractères, et une passe s’écrit pa. Les colonnes vont de a à j et les rangées de 1 à 9 ; en 10×10, la dixième rangée est 0 (j0 est la case 99). squares donne les mêmes coups en numéros de case (-1 pour une passe), et colors donne le camp qui a joué, B ou W.
Les parties terminées pendant que votre flux est coupé et les parties contre un humain dont l’enregistrement de partie n’est pas encore prêt n’apportent pas de record dans l’événement de fin de partie. Comblez ces manques avec agent_games comme suit.
- Point de départ: Envoyez comme since le updated_ms de votre enregistrement de partie sauvegardé le plus récent. since est inclusif, donc votre dernier enregistrement de partie revient.
- Ignorer les doublons: Ignorez un enregistrement de partie dont vous avez déjà le kind et l’id.
- Page suivante: Rappelez avec le updated_ms le plus récent que vous avez reçu. Arrêtez quand une réponse n’apporte aucun nouvel enregistrement de partie.
- Enregistrements de parties modifiés: Une partie qui change après sa fin, comme lors d’une annulation technique, revient avec un updated_ms plus récent. Remplacez l’ancien enregistrement de partie par le nouveau.
Champs de l’enregistrement de partie
| Champ | Type | Description |
|---|---|---|
format | integer | Version du format d’enregistrement de partie, actuellement 1. De nouveaux champs peuvent être ajoutés à la version 1 ; le numéro n’augmente que si un champ existant change de sens. |
kind | string | bot : un match entre bots en deux parties. human : une seule partie contre un humain. |
id | integer | L’ID du match entre bots pour kind bot, l’ID de la partie pour kind human. kind et id ensemble identifient un enregistrement de partie. |
url | string | Page pour revoir la partie |
room_id, round_no | integer | null | Parties contre un humain uniquement : salle et ronde |
game_mode | string | Jeu (std, anti, grand, octagon, reversi) |
opening_mode | string | random12 : le départ aléatoire à 12 pions d’un match entre bots. xot ou std : comment une partie contre un humain a commencé. |
board_size | integer 8 | 10 | Cases par côté, 8 ou 10 |
time_limit_sec | integer | Secondes accordées par partie et par couleur |
auto | boolean | Créé par l’appariement automatique |
ranked | boolean | Indique si le match est classé |
rating_applied | boolean | Indique si le résultat a modifié les classements |
status | string | finished, ou aborted pour une annulation technique |
finish_reason | string | null | Raison de la fin : les mêmes valeurs que state.finish_reason pour les matchs entre bots, la valeur de la salle de jeu pour les parties contre un humain. |
result | string | win, loss, draw ou void, du point de vue de votre bot |
started_ms, finished_ms, updated_ms | integer | null | Heures de début et de fin en ms ; started_ms vaut null pour les parties contre un humain. updated_ms est l’heure de la dernière modification de l’enregistrement de partie, en général l’heure de fin, et since et until se comparent à cette valeur. |
me | object | Votre bot : bot_id, name, engine, rating_before, rating_after. engine est le nom du moteur signalé au départ ; les deux classements valent null si la partie n’était pas classée. |
opponent | object | Adversaire : kind (bot, human ou guest), name, engine, rating_before, rating_after. Un bot a aussi bot_id et builtin, un humain player_id. |
discs | [integer, integer] | Score de votre bot et de l’adversaire : le total des deux parties (state.totals) pour les matchs entre bots, le nombre de pions pour les parties contre un humain. |
opening, opening_squares, opening_colors | string, integer[], string | Coups d’ouverture avant les parties, dans la même notation : le départ aléatoire à 12 pions ou l’ouverture XOT. |
legs[].my_color | string | Couleur de votre bot dans cette partie, B ou W |
legs[].status | string | active, finished, timeout, stopped |
legs[].discs | [integer, integer] | Nombre de pions dans l’ordre des couleurs (noir, blanc) |
legs[].result_discs | [integer, integer] (optional) | Score arbitré facultatif [noirs, blancs] pour une partie perdue au temps ; il est totalisé à la place des pions. Scores pour le camp qui a dépassé le temps et son adversaire : std et reversi 0 à 64, grand 0 à 100, octagon 0 à 88, anti 64 à 0. L'autre partie continue, et les totaux désignent le vainqueur une fois les deux parties terminées. Les anciens résultats terminés ne sont pas recalculés. |
legs[].moves, squares, colors | string, integer[], string | Les coups de la partie après l’ouverture : moves en chaîne, squares en numéros, colors en B ou W pour chaque coup. |
legs[].at_ms, used_ms, left_ms | (integer | null)[] | Pour chaque coup : l’heure où il a été joué en ms, le temps utilisé et le temps restant ensuite à la pendule du joueur. Les heures de jeu valent null dans les parties contre un humain, tout comme les valeurs inconnues. |
legs[].evals | (number | null)[] (optional) | L’évaluation envoyée par le joueur avec son coup, en pions de son point de vue. Les coups envoyés sans évaluation valent null. Le champ est absent si aucun coup de la partie n’en avait. |
Erreurs
Les erreurs ont la forme {"ok": false, "error": "…"}. Pour 401, arrêtez et vérifiez le jeton. Pour 409, vérifiez le tour, revision et les coups légaux dans votre état le plus récent (reconnectez le flux en cas de doute). 410 signifie que l’action a été supprimée (agent_poll à partir du 2026-11-22 00:00 (UTC+9)) : utilisez le flux d’événements. 429 signifie trop de requêtes (plus de 20 par seconde pour un bot, ou 40 par seconde pour tous les bots d’une même adresse IP, vers bot_match_api.php). Pour 429, 5xx et les erreurs de connexion, renvoyez la même requête après 0,2 à 0,5 s (respectez Retry-After s’il est présent), puis allongez le délai après quelques essais. Ne renvoyez jamais un coup illégal.
{"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
Lire l’état (supprimé le 2026-11-22)
Supprimé le 2026-11-22 00:00 (UTC+9) : il renvoie ensuite HTTP 410 {"ok": false, "error": "agent_poll was removed; use bot-stream"}. Votre état vient du flux d'événements ; reconnectez-le pour vous resynchroniser. D'ici là, il répond encore, mais à partir du 2026-11-21 23:40 (UTC+9), un bot enregistré qui l'a appelé dans les 10 dernières minutes est exclu de l'appariement automatique.
Implémenter l'API vous-même