APIドキュメント

初めての方向けの手順

用意するもの

  • FlipSightのアカウント。
  • ボットの写真1枚。GIF、JPG、PNGで5MB以下、縦横とも175px以上の画像です。
  • ボットを動かす自分のコンピューター1台 ボットの手は、接続プログラムを動かしている自分のコンピューターで計算されます。同じエンジンでも、コンピューターの性能やエンジンの設定によって強さが変わることがあり、コンピューターや設定を変えるとレーティングもそれに合わせて動くことがあります。
  • Python 3。接続プログラムを動かす無料のプログラムです。3.9以上で動き、3.11以上をおすすめします。手順5で確認します。
  • 自分のボットエンジン。接続プログラムにはテスト用の練習エンジンが付属しています。

1. ボットを登録する

ログインしてボットページ(othelloclub.com/ja/flipsight/lab)を開きます。いちばん上の自分のボットを登録の欄で、ボット名(2~24文字)に名前を入力します。対応ゲームは最初は標準だけにチェックが入ったままにします。ボット写真をアップロードで写真を選び、自分のボットを登録ボタンを押します。

成功の目安:接続トークン(今回のみ表示)の枠が表示され、fsbm_で始まる長い文字列が入っています。

2. トークンを保管する

この長い文字列がトークン(ボット専用のパスワード)です。接続プログラムがサーバーに「このボット本人です」と証明するときに使います。枠の中をすべてコピーし、メモ帳などに一時的に貼っておきます。枠を閉じると同じトークンはもう表示できません。

トークンはパスワードと同じように扱います。人に見せたり、画面を撮って投稿したりしないでください。なくしたときや人に見られたときは、ボット一覧の管理を開いて接続トークンを発行を押します。新しいトークンを受け取ると、古いトークンはすぐに使えなくなります。

3. 接続プログラムをダウンロードする

FlipSight ボット接続プログラム一式 (.zip)を押してZIPファイルをダウンロードし、展開します。展開したフォルダーをこの手順では「ボットフォルダー」と呼びます。デスクトップなど見つけやすい場所に置きます。

成功の目安:ボットフォルダーの中にREADME.mdファイルとtoolsフォルダーがあります。

4. ボットフォルダーで端末を開く

端末はコマンドを文字で入力する画面です。お使いのOSに合わせて開きます。

macOS:Command+Spaceを押してTerminalと入力し、開きます。cdと空白1つを入力し、ボットフォルダーを画面にドラッグしてからEnterを押します。

Linux:ファイルマネージャーでボットフォルダーを右クリックし、「端末で開く」を選びます。メニュー名はディストリビューションによって違うことがあります。ない場合は端末を開き、macOSと同じようにcdで移動します。

Windows:エクスプローラーでボットフォルダーを開きます。上のアドレス欄にpowershellと入力してEnterを押すと、そのフォルダーでPowerShellの画面が開きます。

確認:下のコマンドを入力してEnterを押します。一覧にREADME.mdとtoolsが表示されれば成功です。このコマンドはmacOS、Linux、Windows PowerShellで共通です。

ls

5. Pythonを確認する

同じ画面で、お使いのOS用のコマンドを1つコピーして貼り付け、Enterを押します。コード枠の右上にあるコピーボタンを使えます。

macOS / Linux

python3 --version

Windows PowerShell

py --version

成功の目安:Python 3.11.9のように3で始まる番号が表示されます。3.9以上なら使えます。コマンドが見つからないと表示されたら下のようにインストールし、画面を閉じて手順4からやり直します。

macOS:python.orgからmacOS用インストーラー(.pkg)を入手してインストールします。終わったら「アプリケーション」のPythonフォルダーにあるInstall Certificates.commandを一度実行します。安全な通信(HTTPS)に必要な証明書を準備する手順です。

Linux:ディストリビューションのソフトウェア管理やパッケージ管理でpython3をインストールします。

Windows:python.orgからPython install managerをインストールします。

python.org

6. トークンを入力する

トークンを環境変数(今開いている端末の画面の中だけで使う一時的な設定)に入れます。名前はFS_BOT_TOKENです。下からお使いのOS用の1行のコマンドをコピーして貼り付け、Enterを1回押します。するとBot tokenと表示され、入力待ちになります。そこで手順2でコピーしたトークンを貼り付けてEnterを押します。

macOS / Linux

printf 'Bot token: '; read -r -s FS_BOT_TOKEN; printf '\n'; export FS_BOT_TOKEN

Windows PowerShell

$env:FS_BOT_TOKEN = [Net.NetworkCredential]::new('', (Read-Host 'Bot token' -AsSecureString)).Password

macOSとLinuxでは貼り付けたトークンが画面に表示されず、Windowsでは文字の代わりに*が表示されます。どちらも正常です。トークンをコマンドに直接書かないので、コマンド履歴に残りません。この設定はこの画面の中でだけ有効です。画面を閉じたり新しい画面を開いたりしたときは、手順4と6をやり直します。

PowerShellではCtrl+Vでトークンを貼り付けます。

成功の目安:エラーなしで次のコマンドを入力する行が表示されます。

7. 接続プログラムを起動する

同じ画面で、下のコマンドをそのままコピーして貼り付け、Enterを押します。コマンドの中のファイル名は変えません。練習用エンジン(打てるマスのうち番号がいちばん小さいマスに打つ、とても弱いエンジン)で接続します。

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'

実行中に文字が表示されず、次の入力待ちに戻らないのは正常です。ボットをオンラインに保つには、このウィンドウを開いたまま接続プログラムとエンジンを実行し続け、コンピューターがスリープしないようにしてください。このウィンドウを閉じるかCtrl+Cを押すと、接続プログラムとエンジンが終了し、ボットはオフラインになります。再びオンラインにするには、上のコマンドをもう一度実行してください。他のボットからの対局申し込みは接続プログラムが自動で承諾します。

練習用エンジンで動かしている間は自動ボット対戦が組まれず、自分で申し込んだボット同士の対局もレーティングに反映されません。10の手順のように自分のエンジンに替えて起動し直すと、その時から自動対戦とレーティングの対象になります。

成功の目安:ボットページの登録ボット一覧で、自分のボット名の右の点が緑色です。点にマウスを重ねるとオンラインと表示されます。

8. 最初の対局で試す

ボットページの対戦する自分のボットで自分のボットを選びます。FlipSightボットの一覧から好きなボットを選んで対戦申込を押し、表示された画面でもう一度確認します。どのゲームの種類でもFlipSightボットの手をサーバーが計算するので、対局室を開いておく必要はありません。

成功の目安:対局室に盤が2面表示され、自分のボットの手番ごとに石が置かれます。練習用エンジンはとても弱いので、負けるのが普通です。

9. 画面を閉じても動かし続ける(任意)

初対局が終わったら、手順7のウィンドウでCtrl+Cを押して接続プログラムを終了します。同じウィンドウで下のコマンドを実行します。稼働中はパソコンをスリープさせないでください。

macOS / Linux

screenを使います。mybotはボットごとに違う名前にします。起動後、Ctrl+Aに続けてDを押すとウィンドウを閉じられます。終了するときは下のコマンドで戻り、Ctrl+Cを押します。

起動

screen -S mybot python3 tools/bot_match_client.py --engine-threads 1 --engine 'python3 tools/bot_match_example_engine.py'

停止

screen -r mybot

Windows PowerShell

Windows:タスクバーに最小化された画面が1つでき、ボットはその中で動きます。今のPowerShellの画面は閉じてかまいません。止めるときは最小化された画面を開いてCtrl+Cを押すか、その画面を閉じます。

起動

Start-Process py -ArgumentList 'tools/bot_match_client.py --engine-threads 1 --engine "py tools/bot_match_example_engine.py"' -WorkingDirectory $PWD -WindowStyle Minimized

10. 自分のエンジンに切り替える

練習用エンジンで接続を確認したら自分のエンジンに切り替えます。Edax・Egaroucidは下の専用オプション、それ以外のNBoard対応エンジンは--nboard、自作エンジンはJSONを使います。トークンはそのまま使えます。

変則ゲーム(アンチ、10x10、八角、クラシックリバーシ)は、エンジンがそのルールを知っている場合だけ対応ゲームにチェックします。チェックしたゲームは、ほかのボットや人から申し込まれます。変更するときはボット一覧の管理で対応ゲームを直し、保存を押します。進行中の対局や承認待ちの申し込みがあるときは変更できません。

よくあるつまずき

症状原因と対処
ボットが灰色の点(オフライン)で表示される。接続プログラムの画面が動いているか確認します。画面を閉じた、Ctrl+Cを押した、パソコンがスリープした場合は止まっています。
コマンドが見つからないと表示される。
command not found / is not recognized
Pythonが入っていないか、インストール後に画面を開き直していません。手順5を見て、新しい画面を開き手順4からやり直します。
ファイルを開けないと表示される。
can't open file
ボットフォルダー以外の場所で実行しています。手順4のようにボットフォルダーへ移動し、lsでREADME.mdとtoolsが表示されるか確認します。
トークンがないと表示されてすぐ終わる。
FS_BOT_TOKEN is missing or invalid
この画面にはトークンがありません。新しい画面を開いた場合は手順6をやり直します。
トークンが拒否されたと表示されて止まる。
Bot credential rejected
トークンの貼り付けを間違えたか、古いトークンです。新しいトークンを発行したりボットを無効にしたりすると、古いトークンは使えません。最新のトークンで手順6からやり直します。
同じエラー行が何度も表示される。
Connection/state error
インターネット接続を確認します。macOSなら手順5のInstall Certificates.commandを実行したか確認します。対局中だけ表示されるなら、エンジンの手をサーバーが反則として拒否している可能性があります。接続プログラムは同じ手を送り直すので、エンジンを直す必要があります。
対局申込ボタンが押せない、または申し込みが承認されない。対戦する自分のボットを選び、両方のボットがオンラインか確認してください。相手が直接の申し込みを受け付け、対局枠に空きがあれば申し込めます。応答のない申し込みは120秒で失効します。
手を打たずに時間切れ負けや無効になる。
Engine failed for match
エンジンが時間内に答えなかったか、答えの形式が間違っています。エンジンの起動コマンドと1行のJSON出力を確認します。開始から30秒以内に初手を打たないと、その対局は無効になります。
変則ゲームの申し込みが来ない。申込画面には両方のボットが対応するゲームだけが表示されます。自分のボットの対応ゲームでそのゲームにチェックしたか、相手のボットも対応しているか確認します。--edax や --nboard で接続したボットは標準だけにチェックします。

用語の説明

用語意味
APIプログラム同士が決まった形式で要求と応答をやり取りする窓口です。接続プログラムが代わりに処理します。
トークン自分のボット専用のパスワードです。接続プログラムがサーバーにボット本人であることを証明するときに使います。
端末コマンドを文字で入力する画面です。WindowsではPowerShellを使います。
環境変数ひとつの端末画面から起動するプログラムに渡す一時的な設定です。画面を閉じると消えます。
JSONデータを文字で書く形式です。例:{"move":19}
エンジン局面を見て手を選ぶプログラムです。
アダプター自分のエンジンと接続プログラムの間でデータ形式を変換する小さなプログラムです。
NBoardオセロのエンジンと盤面プログラムが局面と手をやり取りする公開の通信規格です。NTestのように対応したエンジンはアダプターなしで接続できます。
合法手今打てるマスです。サーバーがlegal_movesで知らせます。

自分のエンジンを接続する

1エンジンあたり最大4スレッドで実行してください。 ボット対戦では2局が同時に進行するため、1対戦の合計は最大8スレッドです。

Edax: --edax

以下のインストール・起動例は、Edax 4.6とEgaroucid for Console 7.8.2を基準にしています。

Edax 4.6は接続プログラムに含まれていません。Edax 4.6のAssetsからOSに合うファイルをダウンロードし、ボットフォルダーに置いて下の準備コマンドで展開してください。Windows・Linuxのコマンドはx86-64用です。

Windows PowerShell (x86-64): edax-4.6-MS-windows-x86.zip

準備(最初の1回だけ)

Expand-Archive -LiteralPath edax-4.6-MS-windows-x86.zip -DestinationPath edax-4.6

起動

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

準備(最初の1回だけ)

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-64

起動

python3 tools/bot_match_client.py --engine-threads 2 --edax "edax-4.6/lEdax-x86-64"

macOS: edax-reversi-4.6.tar.gz

Edax 4.6の公式macOS実行ファイルはありません。同じページのSource code (tar.gz)とedax-4.6-linux-x86.tar.gzをダウンロードしてください。ソースからMac用をビルドし、Linuxのアーカイブからは共通の評価ファイルdata/eval.datだけを取り出します。Xcodeコマンドラインツールが必要です。下の準備コマンドはソースをコンパイルします。

準備(最初の1回だけ)

xcode-select --install
tar -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)

起動

python3 tools/bot_match_client.py --engine-threads 2 --edax "edax-4.6/bin/mEdax-native"

Edaxは、以下のように--edaxに実行ファイルのパスだけを指定しても接続できます。別のアダプターは不要です。接続プログラムはEdaxをxboard方式で起動し、毎手の前に双方の残り時間を送ります。考える時間はEdaxが自分の持ち時間から決めます(接続プログラム v1.4.8 以降)。局の途中は棋譜とハッシュを引き継ぎ、--engine-ponder on なら相手の手番中も探索します。従来のNBoard接続は --edax-protocol nboard で使えます。

コマンドのパスを自分の実行ファイルの絶対パスに変えてください。空白を含むパスは二重引用符で囲みます。評価ファイルが自動で見つからない場合は--edax-evalでeval.datを指定してください。

--edax と --nboard の接続は通常(8×8)だけに対応します。このボットは対応ゲームで標準だけにチェックしておきます。変則の対局が来ると接続プログラムはエンジンに問い合わせないので手が打てず、その対局は無効か時間切れ負けになります。

Egaroucid: --egaroucid

Egaroucid for Consoleを用意してください。画面用アプリではなくコンソール版の実行ファイルを指定し、resourcesフォルダーは元の場所に置きます。macOS・Linuxでは公式手順でビルドした実行ファイルを使います。独自のsetboard、settime、goコマンドで局面と残り時間を渡すため、アダプターを作る必要はありません。

Egaroucid for Console

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"

どちらも通常の8×8専用で、2局同時の場合は各局に1つずつエンジンを起動します。--max-think-secondsは1手の安全上限です(既定10秒)。Egaroucidが上限に達したら探索を終了して代わりに合法手を打ち、次の手番でエンジンを再起動します。

NTestなどのNBoardエンジン: --nboard

NBoardはNTestと組み合わせて使えるオセロの画面プログラムです。NBoardプロトコルは、このプログラムとエンジン間の公開通信規格で、NTestなどこの規格に対応したエンジンは --nboard で接続します。エンジンは局ごとに1つずつ起動したままにします。Edaxもこの規格に対応していますが、Edaxは上の --edax で接続してください。

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"

--edax と --nboard の接続は通常(8×8)だけに対応します。このボットは対応ゲームで標準だけにチェックしておきます。変則の対局が来ると接続プログラムはエンジンに問い合わせないので手が打てず、その対局は無効か時間切れ負けになります。

自作エンジン:JSONで接続

ここは自作エンジンをつなぎたい方だけが読めば十分です。Edax、Egaroucid、NBoard対応エンジンは上の方法で接続が終わっているので、読み飛ばしてください。

接続プログラムは、自分のボットの手番が来るたびに my_adapter.py を1回実行します。今の局面(石の位置、どちらの手番か、打てるマス、残り時間)を1行で渡し、my_adapter.py が打つマスを1行で答えると、その手を代わりにサーバーへ送ります。my_adapter.py はその間で自分のエンジンに手を尋ねる小さな Python ファイルです。サーバーへの接続、トークン、着手の送信は接続プログラムが行うので、このファイルでは気にしません。

FlipSight→ bot_match_client.py→ my_adapter.py
FlipSight← bot_match_client.py← my_adapter.py

自分のエンジンはどれですか?

  • Python のコードで手を選ぶエンジン:下の例 A を使います。
  • 実行ファイルで、1回実行すると答えを1行出して終わるエンジン:下の例 B を使います。
  • 実行ファイルで、起動したまま命令をやり取りし続けるエンジン:NBoard規格に対応していれば上の--nboardで接続します。別の規格なら例Bをその規格に合わせて直し、エンジンを起動したままmy_adapter.pyが1行ずつやり取りを繰り返すようにします。

ステップ1:接続だけを確かめるファイル (my_adapter.py)

ボットフォルダー(README.md と tools がある場所)に my_adapter.py というファイルを作り、下の内容をそのまま貼り付けて保存します。このファイルはエンジンを使わず、打てる最初のマスを答えるだけです。自分のエンジンをつなぐ前に、接続できるかを確かめるためのものです。

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)

サーバーに接続する前に入出力を確認

1の箱のコマンドは例の局面をアダプターに直接入れてみます。正常なら{"move": 19}が1行表示されます。その行が出たら、2の箱のコマンドでこのアダプターを使って接続プログラムを起動します(手順6のトークンがある画面で)。2つの箱は別々に実行します。エンジンがこのJSON形式を直接読めるなら、--engineにエンジンの起動コマンドをそのまま書いてもかまいません。

1. アダプターだけを試す

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.py

Windows 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.py

2. アダプターで接続プログラムを起動

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'

ステップ2:自分のエンジンを呼ぶファイルに替える

ステップ1ができたら、my_adapter.py の中身を下の例 A か例 B に丸ごと置き換えます。直すのは EDIT と書かれた行だけで、ほかはそのままにします。置き換えたら上のテスト用コマンド1をもう一度実行し、答えが1行出るか確かめてください。エンジンが選んだ手なので、19 以外のマスが出ても正常です。

例 A:Python の関数で手を選ぶエンジン

my_engine.py というファイルに手を選ぶ search 関数があると仮定した例です。EDIT 1 でファイル名と関数名を、EDIT 2 で渡す値を自分のエンジンに合わせて直します。関数は打つマスの番号(0~63)か 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)
例 B:実行ファイルのエンジン

実行ファイルが盤面64文字、手番、考える時間(ミリ秒)を1行で受け取り、D3 のような座標を1行で答えると仮定した例です(.=空き、X=黒、O=白)。形式はエンジンごとに違うので、EDIT 1 で実行ファイル名を、EDIT 2 でエンジンへ送る行を、EDIT 3 で答えを読む部分を自分のエンジンに合わせて直します。

my_adapter.py → my_engine

...........................OX......XO........................... X 1777

my_engine → my_adapter.py

D3
import 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)

考える時間:ボット対局は1局ごとの持ち時間が1分なので、1手に長く使うとすぐ時間切れ負けになります。例の think_ms は残り時間(remaining_ms)を自分の残り手数で割って、この手に使う時間を決めます。budget_ms はこの手に使ってよい時間ではなく、接続プログラムが答えを待つ最長時間(既定は10秒)です。これを過ぎるとその局はそれ以上打てず時間切れ負けになるので、エンジンには budget_ms ではなく think_ms の値を渡してください。

うまく動かないとき:例のファイルは、エンジンの呼び出しに失敗すると理由を my_adapter.log に書き、打てる最初のマスを代わりに打ちます。手がおかしいときは、まずこのファイルを開いてください。接続プログラムはアダプターのエラーメッセージを画面に表示しません。print は答えの1行だけに使い、確認用の文字はファイルに書いてください。

速さ:接続プログラムは対局ごとにmy_adapter.pyを起動したままにし、1手ごとに1行送ります。例のように1行答えて終了するファイルなら次の手で起動し直すので、エンジンも毎回起動し直します。エンジンの起動に時間がかかる場合や前の手の計算を引き継ぎたい場合は、my_adapter.pyを「1行読んで1行答える」を繰り返す形にしてください。入力を最後まで読まず、答えるたびにflushします。

以下は、接続プログラムと my_adapter.py がやり取りする内容を説明した参考資料です。上の例のファイルをそのまま使うなら、読まなくてもかまいません。

入力JSON(接続プログラム → アダプター)

以下は実行コードではなく、接続プログラムが送るデータの例です。Pythonファイルとして保存する必要はありません。対局中は現在のデータが毎手自動で届きます。

下は通常8×8の初期局面の例です。実際には接続プログラムが現在の局面を入れて送ります。boardはa1から右へ読み、次の段へ進むマスの配列で、0=空き、1=黒、2=白です。color=1なら黒の手を選びます。legal_movesは今打てるマスの番号です。remaining_msは残りの持ち時間、budget_msは接続プログラムが今回の手の答えを待つ最長時間で、単位はミリ秒(1000=1秒)です。変則ゲームのフィールドと例は下の「変則ゲーム」の節にあります。

{"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(アダプター → 接続プログラム)

応答は下の例のいずれかをJSON1行で書き、改行で終えます。moveにはマス番号か座標を入れ、大文字と小文字は区別しません。8×8のd3は(3−1)×8+3=19です。必ず受け取ったlegal_movesの中から選びます。ボット同士の対局で打てる場所がなければ-1かpassを送ります。人との対局の強制パスはサーバーが処理します。stdoutには応答の1行だけを書き、ほかの案内文を混ぜません。

{"move":19}
{"move":"d3"}
{"move":-1}

任意: 応答に environment を入れると、エンジンの実際のスレッド数、ハッシュ MB、先読みの有無を報告できます(接続プログラム v1.4.6 以降)。接続プログラムは範囲内の数値と true/false だけを受け取りボット情報に反映します。自作のアダプターが eval を入れると、接続プログラムはボット同士の対局で手と一緒に送ります(例: {"move":19,"eval":1.5})。値は打った後の自分側から見た石数でそのゲームのマスの数までとし、--edax、--egaroucid、NBoard エンジンは v1.5.3 に更新すれば自動で送ります。

{"move":19,"environment":{"engine_threads":1,"hash_mb":32,"ponder":false}}

種目別のエンジンへの要求の例

ダウンロード

FlipSight ボット接続プログラム一式 (.zip)

GitHub: flipsight-othello-bot-connector

OpenAPI 3.1 JSON

README.md

最初の項目は説明書とtoolsフォルダーの接続プログラムと例のエンジンをまとめた圧縮ファイル(.zip)です。API仕様(.json)と説明書(.md)は個別ファイルです。

APIを直接実装する場合

練習用の接続プログラムは先に終了します。手順6のトークンでストリームを開きます。接続はトークンごとに1本です。各行にJSONイベントが1件届きます。

イベントストリーム

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"

helloの次にstateが届きます。自分のボットが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]
                    }
                ]
            }
        }
    ]
}

2局目(leg 1)では自分のボットが黒(1)です。turnが1なら、legal_movesから一手を選び、この盤のrevisionと一緒に送ります。実際に送るときは別の端末で手順6のトークンを設定し、現在の対局の値を使います。

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}'

agent_accept, agent_move

イベントストリーム

APIを直接実装する場合

型説明
hello接続完了。bot_idが自分のボット番号です。
state進行中の対局と申し込みの一覧を置き換えます。自分がbot_bのpendingの申し込みはagent_acceptで受けられます。
match同じidの対局を更新し、進行中の各盤で自分の手番を確認します。
ping10秒ごとの接続確認です。返信は不要です。
closingサーバーが接続を閉じる直前に送る最後の行です。reasonがoverflow(送れない行がたまった)かserver_shutdownなら、再接続してstateで追いつきます。replacedは同じトークンが別の場所でも使われているという意味です。すぐに再接続せず30秒以上待ち、繰り返す場合は待ち時間を延ばします。トークン1つは1か所だけで使います。
対戦オブジェクト(matches[])
フィールド型説明
idinteger対戦ID(人との対局は負の値)
kindstring人との対局ならhuman
bot_ainteger参加者0のボットID(人なら0)
bot_binteger参加者1のボットID(人なら0)
game_modestringゲーム(std、anti、grand、octagon、reversi)
time_limit_secinteger局ごと、色ごとの持ち時間(秒)
statusstringpending, running, finished, aborted, rejected, expired
expires_msinteger承諾期限(ミリ秒)
rankedbooleanレーティング対戦かどうか
state.statusstringactive、finishedまたはaborted
state.game_modestringゲーム(std、anti、grand、octagon、reversi)
state.board_sizeinteger 8 | 10盤の1辺のマス数、8または10
state.blocked_squaresinteger[]使えないマスの番号(八角のみ、番号順ではない)
state.legsarray局の一覧(ボット同士は2局、人とは1局)
state.totals[integer, integer]参加者ごとの2局の判定点合計(result_discsがなければdiscsを使用)
state.winnerinteger | null勝った参加者 0 または 1、引き分けはnull
state.finish_reasonstring | nulldiscs, timeout, double_timeout, disconnect, no_first_move
局オブジェクト(state.legs[])
フィールド型説明
boardinteger[64 | 100]64 / 100マス、0=空 1=黒 2=白
turninteger手番の色、1(黒)または2(白)
legal_movesinteger[]手番の色が打てるマス。終わった局は空の配列
placed{"1": integer, "2": integer}色ごとに置いた石の数、キーは"1"(黒)、"2"(白)
black_participantintegerこの局で黒を持つ参加者
clocks_ms[number, number]色の順(黒、白)の残り時間の基準値
turn_started_msinteger現在の手番が始まったサーバー時刻
revisionintegerこの局が変わるたびに1増加
statusstringactive, finished, timeout, stopped
historyarray打った手の一覧(color, participant, move, at_ms, eval)
discs[integer, integer]色の順(黒、白)の石数
result_discs[integer, integer] (optional)時間切れになった局の合計用の判定点[黒, 白](任意のフィールド)。ある場合はdiscsの代わりに合計します。時間切れ側と相手の点数はstdとreversiが0対64、grandが0対100、octagonが0対88、antiが64対0です。もう一方の局は続き、両局が終わったあと合計で勝敗を決めます。過去の終了済みの記録は再計算しません。

対局が終わると、最後のmatchイベントに対局記録recordも入ります。そのまま保存すれば、対局全体が残ります。 対局記録

状態の同期

切断時や15秒間何も届かないときは、1秒から最大30秒まで間隔を延ばして再接続します。古い状態は破棄します。人との対局ではroom_created_at、round_no、revisionの順に比較します。着手の応答を失ったら、同じ盤のrevisionと自分の手番を確認してから再送します。

起動時と設定変更時にagent_environmentでエンジン情報を送ります。自動マッチングのv2基準は、直近のオンライン10分間でストリーム接続10回以下、agent_poll呼び出し0回です。

認証

HTTPSのJSON POSTとAuthorization: Bearerを使います。トークンはそのボット専用です。URL、公開コード、ログに含めないでください。

Content-Type: application/json
Authorization: Bearer <FS_BOT_TOKEN>

POST https://othelloclub.com/flipsight/bot_match_api.php

接続プログラムのオプション

tools/bot_match_client.pyに指定できる起動オプションです。--engineと--nboard / --edax / --egaroucidのいずれか1つは必ず指定します。トークンはオプションではなく、環境変数FS_BOT_TOKENからだけ読み込みます。終了コードは0(正常終了)、2(トークン拒否)、3(--max-runtime到達)です。

パラメーター説明
--engine "COMMAND"対局ごとにこのコマンドを1回起動したままにし、1手ごとにJSONを1行送って1行受け取ります(入力は閉じません)。1行答えて終了するエンジンは次の手で起動し直します。
--nboard "COMMAND"NBoardエンジンを局ごとに1つ、合計2つ動かしたままにします。通常(std)専用です。
--edax PATHEdaxは、以下のように--edaxに実行ファイルのパスだけを指定しても接続できます。別のアダプターは不要です。接続プログラムはEdaxをxboard方式で起動し、毎手の前に双方の残り時間を送ります。考える時間はEdaxが自分の持ち時間から決めます(接続プログラム v1.4.8 以降)。局の途中は棋譜とハッシュを引き継ぎ、--engine-ponder on なら相手の手番中も探索します。従来のNBoard接続は --edax-protocol nboard で使えます。
--edax-eval PATHEdaxの評価ファイルeval.datのパスです。省略すると実行ファイルのフォルダー、またはその親のdata/eval.datを探します。
--edax-protocol xboard|nboard--edax の接続方式です。既定の xboard では Edax が自分の持ち時間で時間を決め、先読みもできます(v1.4.8 以降)。nboard は v1.4.7 までの方式で、接続プログラムが毎手の時間を決め、先読みはしません。
--egaroucid PATHEgaroucid for Consoleを用意してください。画面用アプリではなくコンソール版の実行ファイルを指定し、resourcesフォルダーは元の場所に置きます。macOS・Linuxでは公式手順でビルドした実行ファイルを使います。独自のsetboard、settime、goコマンドで局面と残り時間を渡すため、アダプターを作る必要はありません。
--egaroucid-level N--egaroucidと一緒に使います。1~60ならEgaroucidをそのレベルで起動し(-level N)、残り時間(settime)を送りません。0または省略時は対局の残り時間に合わせる時間モードです。レベルモードには探索を途中で止めるコマンドがないため、1手が--max-think-secondsの上限を超えると、接続プログラムがエンジンを止めて合法手を1つ代わりに打ちます。対局の持ち時間内に余裕を持って終わるレベルを選んでください。
--nboard-depth NNBoardエンジンにset depth Nを送ります。0~60で、0ならエンジンの既定値です。 --edaxと一緒に使うと、この値がEdaxのレベルになります(20ならL20)。省略すると60です。Edaxはレベルに達するか、その手の時間が尽きるか、早い方の時点までの最善手を打ちます。--edax には xboard の sd N として送ります。
--max-think-seconds S1手でエンジンを待つ最大時間(秒)です。既定は10、最大300。残り時間から0.75秒を引いた値より長くはしません。接続プログラム側の安全上限で、サーバーには1手ごとの時間制限はありません。 0なら別の1手上限を設けず、対局の残り時間を使います。 対局の持ち時間はサイトが決め、接続プログラムでは変えられません。ボット同士の対局と自動ボット対戦は局ごと、色ごとに60秒で、人が直接申し込んだ対局は申し込んだ人が選びます。--edax では、この上限の中でEdaxが自分の持ち時間から1手の時間を決め、上限に達すると接続プログラムがその時点の最善手をすぐ打たせます。
--engine-name NAMEボット情報に報告するエンジン名(120文字以内)です。コマンドやパスは入れません。
--engine-threads N1局でエンジンが使うスレッド数です。ユーザー記録に表示されます。--edax、--egaroucid ではこの値でエンジンを起動し、省略時は論理CPUが4個より多ければ4、それ以外は1です。--engine には各リクエストの engine_threads として送ります。 1エンジンあたり最大4スレッド、2局同時進行の1対戦では合計最大8スレッドで実行してください。 --engine・--nboard は省略時に入力を求め、バックグラウンド・自動実行ではこの指定が必須です。
--engine-hash-mb MBエンジン1個あたりのハッシュ容量(MB)です。--edax と --egaroucid では、この値以下で最大の2の累乗の大きさにエンジンのハッシュを設定し(Edax -h、Egaroucid -hash)、その大きさを報告します。省略時はEdaxはedax.ini、Egaroucidは32 MBです。ほかのエンジンは報告だけで設定は変わりません。ハッシュはエンジンごとに確保されるため、2局を同時に進めるボット対局では2倍になります。
--engine-ponder on|off先読み(相手の手番中も探索)の設定です。--egaroucid に on を指定するとEgaroucidを -ponder で起動し、オンを報告します。相手の手番中もCPUを使います。--edax に on を指定すると、Edax は xboard 方式(hard)で相手の手番中も探索し、オンを報告します(接続プログラム v1.4.8 以降)。--edax-protocol nboard では Edax は先読みしないため、on は受け付けません。ほかのエンジンは実際の設定を報告するだけです。
--cpu-name NAME報告するCPU名(120文字以内)です。省略すると自動で調べます。
--once-match IDこの対局だけを処理し、終わったら(finished、aborted、expired、rejected)終了します。人との対局の負のIDも使えます。試験では--max-runtimeと一緒に使います。
--max-runtime S指定した秒数が過ぎるとエンジンを片付けて終了します(終了コード3)。
--save-games DIRオンにすると、それ以降に終わった対局をすべてDIR/games-YYYY-MM.ndjsonに、1行に対局記録1件ずつ保存します(既定はオフ)。接続プログラムが止まっていた間やストリームが切れていた間に終わった対局は、再接続時に保存済みの最新の対局からagent_gamesで埋めます。1対局は約4KB(10×10は約6KB)なので、1日1,400対局なら1日約6MB、1か月約180MBになります。不要になった古い月のファイルはご自分で削除してください。
--timing-log PATH1手ごとに時間の内訳(相手の手の受信、探索の空き待ち、エンジン、着手の送信)をファイルに1行ずつ追記します。既定ではオフで、サーバーに余分なものは送りません。
--api URL, --stream-url URLAPIとストリームのアドレスです。通常は既定値を使います。HTTPSのみで、トークンも一緒に送られるため、ストリームはAPIと同じホストに限ります。

変則ゲーム

ボットは対応ゲームでチェックしたゲームだけを受けます。エンジンへの要求と状態のgame_modeで種目がわかります。盤の大きさ、使えないマス、打てるマスはサーバーが計算して送るので、エンジンは受け取ったlegal_movesの中から選べば十分です。通常8×8用の計算で10×10やクラシックリバーシの手を作らないでください。

ゲームgame_mode盤
標準std8×8
アンチ (Anti)anti8×8
10x10 (Grand)grand10×10
八角 (Octagon)octagon10×10 (88)
クラシックリバーシreversi8×8

共通:黒(1)が先に打ちます。2局は同じ開始局面から黒白を入れ替えて同時に進みます。ボット同士の対局で打てる場所がないとlegal_movesが空の配列で届き、ボットがmove=-1(パス)を自分で送る必要があります。サーバーは代わりにパスせず、その間も自分の持ち時間は減ります。打てる場所があるのにパスすると反則です。両方の色が打てなくなるとその局は終わります。新しい2局対戦では通常終了した各局の空きマスを石が多い色に加算し、2局の得点を合計します。アンチは補正後の合計が少ない側の勝ちで、同数には空きマスを加算しません。合計が同じなら引き分けです。すべてのボット戦は、ランダムに作った12石の局面から始まります。すべてのゲーム種類で、各局の各ボットの持ち時間は1分です。

アンチ:置き方と返し方は通常と同じです。2局の石の合計が少ない方が勝ちです。

10x10:10×10の盤(100マス)で通常のルールで打ちます。ルール上の初期配置は中央の4マスで、ボット戦はそこにランダムな8手を加えた12石から始まります。

八角:10x10と同じ盤と初期配置で、四隅の3マスずつ、合計12マスを使いません(使えるマス88)。使えないマスはblocked_squaresにマス番号で届き、boardでは空きマスと同じ0で届きます。配列は番号順ではありません。使えないマスには打てず、石の並びもそこで途切れます。

クラシックリバーシ:ルール上は空の盤から始めます。中央の4マス(27、28、35、36)に空きがある間は、そこにだけ返さずに置きます。4マスが埋まると通常のルールです。各色が置ける石は最初の4手を含めて32個までです。placedは色ごとにこれまで置いた石の数で、キーは文字列の"1"(黒)と"2"(白)です。ボット戦はサーバーが中央の4手を含む12手をランダムに打った局面から始まるので、最初の要求のplacedは2色の合計が12です(通常は{"1":6,"2":6})。32個を置き終えた色はlegal_movesが空の配列になり、手番ごとに-1を送ります。

種目別のエンジンへの要求の例

接続プログラムが--engineのエンジンに送る黒の最初の要求を、ルールのコードで作った例です。実際の対局はどの種目もランダムな12石の局面から始まるので、boardとlegal_movesは対局ごとに変わります。この例は表示のたびに変わらないよう、開始の手を盤の中央に近いマスに固定して作りました。match_idと持ち時間の値も実際の対局では変わります。

アンチ (Anti) (anti)

入力JSON(接続プログラム → アダプター)

{
    "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(アダプター → 接続プログラム)

{"move":2}
10x10 (Grand) (grand)

入力JSON(接続プログラム → アダプター)

{
    "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(アダプター → 接続プログラム)

{"move":13}
八角 (Octagon) (octagon)

入力JSON(接続プログラム → アダプター)

{
    "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(アダプター → 接続プログラム)

{"move":13}
クラシックリバーシ (reversi)

入力JSON(接続プログラム → アダプター)

{
    "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(アダプター → 接続プログラム)

{"move":18}

エンジンへの要求のフィールド

フィールド型説明
game_modestringstd、anti、grand、octagon、reversiのいずれか。人との対局のXOTはstdで届きます。
board_sizeinteger 8 | 108。grandとoctagonでは10。
boardinteger[board_size²]長さboard_size²の配列。a1から右へ読み、次の段へ進みます。0=空き(八角の使えないマスを含む)、1=黒、2=白。
blocked_squaresinteger[]八角の使えないマスの番号。ほかのゲームでは空の配列。
placed{"1": integer, "2": integer}色ごとにこれまで置いた石の数(開始時のランダムな手を含む)。キーは文字列の"1"と"2"。クラシックリバーシの32個制限に使います。
legal_movesinteger[]今打てるマスの番号。空の配列ならmove=-1を返します。
colorinteger 1 | 2打つ色。1=黒、2=白。
budget_msinteger今回の手に使える時間(ミリ秒)。--max-think-secondsと、残り時間から0.75秒を引いた値の小さい方。超えると接続プログラムがエンジンを止めます。
remaining_msintegerこの局の自分の色の残り時間(ミリ秒)。この手番ですでに使った時間を引いた値です。
match_idinteger ≠ 0対局id。人との対局は負の値(-部屋番号)。
leginteger 0 | 1局の番号0または1。人との対局は0。
revisionintegerこの局の状態番号。agent_moveにそのまま送ります。
historyarrayこの局で打った手の一覧。判断はboardで行います。
round_nointeger | null人との対局のラウンド番号。ボット同士の対局ではnull。
room_created_atstring | null人との対局の部屋の作成時刻。ボット同士の対局ではnull。
engine_threadsinteger (optional)接続プログラムを --engine-threads 付きで起動したときだけ入ります。エンジンがこの対局で使うスレッド数で、エンジンはこの値に合わせて探索スレッドを決めます。

ボット同士の変則対局の申し込み

agent_challengeにgame_modeを入れます。省略するとstdです。両方のボットのsupported_gamesに含まれている必要があります。相手が対応するゲームはボットページで確認します。どちらかが対応していないとHTTP 409と下のエラーが返ります。

{"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}

対応ゲーム(supported_games)の変更

登録画面では標準にあらかじめチェックが入っており、対応ゲームを登録していなかった既存のボットはstdです。変更はWebのボットページの管理でだけでき、ボットのトークン(API)では変更できません。進行中の対局や承認待ちの申し込みがあると拒否されます。空の一覧では保存できません。

人と登録ボットの対局

人もボットが登録したゲームで申し込めます。通常に対応していると、STDとXOTの両方が来ることがあります。XOTはgame_modeがstdで届き、すでに8手進んだ盤から始まります(その手はhistoryに入っています)。持ち時間は申し込んだ人が選び、レーティングは適用されません。人との対局は1局(leg 0)で、match_idは負の値です。打てる場所がないときのパスはサーバーが処理するので、-1は送りません。 自動マッチングがオンのオンライン登録ボットは、対応するSTD/XOTのクイックマッチにも参加します。会員のクイックマッチはレーティング対象、ゲストは対象外です。

反則手と時間

反則手や古いrevisionはHTTP 409(illegal_move、stale_revision、not_your_turn)で拒否され、盤は変わりません。その間も持ち時間は減り続けます。接続プログラムは同じ手を同じrevisionで送り直すので、エンジンを直さないと最後にはその局が時間切れ負けになります。サーバーには1手ごとの時間制限はなく、色ごとの残り時間だけを見ます。10秒は接続プログラムの--max-think-secondsの既定値です。

対戦ルール

すべてのボット戦は、ランダムに作った12石の局面から始まります。 同じ局面で白黒を入れ替えた2局を同時に行い、石数の合計で勝敗を決めます。アンチは石数が少ない方が勝ちます。

すべてのゲーム種類で、各局の各ボットの持ち時間は1分です。

開始から30秒以内に初手を打たないボットがいる場合、その対戦は無効(aborted)となり、レーティングに反映されません。対戦中に一方のボットの接続が30秒を超えて切れ、もう一方が接続中の場合は、接続中のボットの勝ち(finish_reason: disconnect)となり、レーティングに反映されます。

FlipSightボットの手は、どのゲームの種類でもサーバーが計算します。ウェブからの申し込みとAPIからの申し込み(agent_challenge)のどちらも受け付け、サーバーがすぐに対局を始めるので、対局室を開いておく必要はありません。サーバーの計算が30秒を超えて止まると、その対局は無効(aborted、finish_reason: technical)となり、レーティングに反映しません。変則ゲームは1手の計算が重いため、FlipSightボットとの変則対局は同時に2局までです。埋まっているとHTTP 409とsite bot variant matches are fullエラーが返るので、少し後でもう一度申し込んでください。

自動マッチングは、双方が選んだ種目でレーティング差が500以内のボットを組み合わせます。接続プログラムが120秒以内に承諾すると対戦が始まり、結果はレーティングに反映されます。登録ボットは管理で種目の選択や自動マッチングの停止ができます。 練習用エンジンで起動したボット(environment.practiceがtrue)は自動ボット対戦の候補から外れ、その間のボット同士の対局はレーティングに反映されません。

人が直接申し込む登録ボット戦は、対応ゲームと時間を選び通常の対局室で1局行います。直接の申し込みはサーバー側で必ずレーティング対象外にします。 自動マッチングがオンのオンライン登録ボットは、対応するSTD/XOTのクイックマッチにも参加します。会員のクイックマッチはレーティング対象、ゲストは対象外です。 登録ボットはボット管理の同時対局数(既定2)までしか対局を受けません。人との対局1局とボット同士の対戦1件(2局)をそれぞれ1と数えます。

対戦の流れ

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)

すべてのボット戦は、ランダムに作った12石の局面から始まります。 同じ局面で白黒を入れ替えた2局を同時に行い、石数の合計で勝敗を決めます。アンチは石数が少ない方が勝ちます。

自分の参加者番号はbot_aなら0、bot_bなら1です。参加者0はlegs[0]で黒(1)、legs[1]で白(2)、参加者1はその逆です。leg.statusがactiveでleg.turnが自分の色なら自分の手番です。2局で同時に自分の手番になることもあります。

合法手がない場合は、move -1(パス)を自分で送る必要があります。サーバーは代わりにパスしません。人との対局では、通常の対局室と同じくサーバーがパスを処理します。

自分の手番での残り時間 = clocks_ms[自分の色 - 1] - (server_now_ms - turn_started_ms)。clocks_msは色の順(黒、白)で、totalsとwinnerは参加者の順です(winnerは0または1、引き分けはnull)。

マス番号

マス番号 = 行 × 8 + 列で、a1=0、h1=7、a2=8、h8=63です。例えば19はd3、37はf5です。board配列も同じ順で、0=空、1=黒、2=白です。

    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 63

10×10(grand、octagon)はマス番号=行×10+列です。列はa~jで、座標の10段目は10または0と書きます。a1=0、j1=9、a2=10、j10=99(j0と同じ)です。同じ座標でも盤の大きさで番号が変わります。たとえばd3は8×8では19、10×10では23です。

     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 99

八角 (Octagon) (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 ## ##

エンジン接続

FlipSight ボット接続プログラム(Python 3.9以上、標準ライブラリのみ)はWindows、macOS、Linuxで動作し、エンジンを2つの方式で接続します。--engineは対局ごとにエンジンを1回起動したままにし、1手ごとにJSONを1行送って{"move": マス番号}を1行受け取ります。1行答えて終了するエンジンも次の手で起動し直すのでそのまま動きますが、入力を最後まで読むエンジン(sys.stdin.read()など)は答えられないので、1行ずつ読むようにしてください。リクエストのlegal_movesは合法なマスの一覧で、空なら-1を返します。--nboardはNBoardプロトコルのエンジンを1局に1つずつ起動したままにし、--nboard-depthで探索深さを指定します。

入力JSON(接続プログラム → アダプター)

接続プログラムのオプション

API操作

レスポンス例は形式を示すものです。コピーボタンはリクエストをコピーするだけで、APIは呼び出しません。

POST agent_environment

接続環境を報告

接続PCのCPU、OS、エンジン名、スレッド数、練習中かどうかを知らせます。起動時と値が変わったときだけ送ってください。応答には自分のボットの情報が入ります。

パラメーター型必須説明
actionstring "agent_environment"必須呼び出すアクション名
environmentobject必須接続PCのCPU、OS、エンジン名(各120文字以内、任意)とpractice(trueかfalse、任意)。practiceがtrueなら練習中という意味で、自動ボット対戦の候補から外れ、その間に申し込んだり承諾したりしたボット同士の対局はレーティングに反映されません。接続プログラムは練習用エンジンで起動するとこの値を自動で送ります。サーバーは最後に受け取った値を覚えているので、練習を終えるときはpracticeなし、またはfalseで送ります。 hash_mb (MB): エンジン1個あたり。接続プログラムの値がなければ手入力できます。 ponder (true / false / null): 表示用の設定です。未報告なら手動で選べます。実際の設定はエンジンで変更します。

リクエスト例

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}}'

レスポンス例

{
    "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

対戦申込

相手はtarget_id(ボット番号)またはtarget_name(ボット名)で指定します。番号と名前はボットページで確認します。FlipSightの標準ボット(is_builtin: true)にも、どのゲームの種類でもAPIで申し込むことができ、サーバーがすぐに対局を始めます。標準ボットとの変則対局がすでに2局進行中だと、HTTP 409とsite bot variant matches are fullエラーが返ります。相手のボットがボット管理で「ボットからの申込」をオフにしていると、HTTP 409 と bot does not accept bot challenges が返ります。ボット同士の自動マッチングはこの設定に関係なく、自動マッチングの設定に従います。

同じボットへの連続申込は3回までです。3回目の対戦が終わってから5分後に再申込できます。

ボットページで対局を申し込む

パラメーター型必須説明
actionstring "agent_challenge"必須呼び出すアクション名
target_idinteger ≥ 1任意申し込む相手ボットのID
target_namestring任意申し込む相手ボットの名前(target_id の代わり)
game_modestring std | anti | octagon | grand | reversi任意ボット同士の対局のゲーム。省略するとstd。両方のボットが対応している必要があります。 標準 / アンチ (Anti) / 八角 (Octagon) / 10x10 (Grand) / クラシックリバーシ

リクエスト例

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"}'

レスポンス例

{
    "ok": true,
    "match_id": 123,
    "server_now_ms": 1800000000000
}

POST agent_accept

承諾

パラメーター型必須説明
actionstring "agent_accept"必須呼び出すアクション名
match_idinteger ≥ 1必須対戦ID(人との対局は負の値)

リクエスト例

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}'

レスポンス例

{
    "ok": true,
    "match": {
        "id": 123,
        "status": "running",
        "bot_a": 1,
        "bot_b": 2
    },
    "server_now_ms": 1800000000000
}

POST agent_reject

辞退

パラメーター型必須説明
actionstring "agent_reject"必須呼び出すアクション名
match_idinteger ≥ 1必須対戦ID(人との対局は負の値)

リクエスト例

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}'

レスポンス例

{
    "ok": true,
    "match": {
        "id": 123,
        "status": "rejected",
        "bot_a": 1,
        "bot_b": 2
    },
    "server_now_ms": 1800000000000
}

POST agent_move

着手を送信

パラメーター型必須説明
actionstring "agent_move"必須呼び出すアクション名
match_idinteger ≠ 0必須対戦ID(人との対局は負の値)
round_nointeger ≥ 0人との対局では必須人との対局のみ: 対戦オブジェクトのround_noをそのまま
room_created_atstring人との対局では必須人との対局のみ: 対戦オブジェクトのroom_created_atをそのまま
leginteger 0 | 1必須局 0 または 1(人との対局は0)
revisioninteger ≥ 0必須着手を計算した局のrevision。局が変わっていれば409 stale_revision
moveinteger -1..99 | string必須マス 0-(board_size²−1)、パスは-1 / d3 / D3 / pass
evalnumber -100..100任意この手を打った後のエンジンの評価値で、打った側から見た石数です(+ なら自分が有利、小数第2位まで)。範囲は打てるマスの数までで、8x8 は -64〜64、10x10 は -100〜100、八角は -88〜88 です。送らない場合や値が正しくない場合は評価値だけを捨て、手はそのまま受け付けます。保存するのはボット同士の対局だけで、対局中も相手ボットを含む全員に見え、人との対局では無視します。

リクエスト例

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}'

人と登録ボットの対局

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"}'

レスポンス例

{
    "ok": true,
    "match": {
        "id": 123,
        "status": "running",
        "bot_a": 1,
        "bot_b": 2
    },
    "server_now_ms": 1800000000000
}

POST agent_games

対局記録のダウンロード

自分のボットの終了した対局を対局記録として返します。応答はNDJSON(Content-Type application/x-ndjson)で、1行が1対局です。ボット同士の対局と人との対局を含み、トレーニング対局と運営アカウントothelloclubとの対局は含みません。技術的な無効になった対局もresult voidとして含みます。

このリクエストではボットはオンラインにならず、API仕様 v2の判定にも数えません。呼び出せるのはボットごとに5秒に1回までで、それより速いと429とretry_after_secが返ります。Accept-Encoding: gzipを送ると、圧縮された応答を受け取れます。

パラメーター型必須説明
actionstring "agent_games"必須呼び出すアクション名
sinceinteger ≥ 0任意含める最も早いupdated_ms(ms)。既定は0。
untilinteger ≥ 0任意含める最も遅いupdated_ms(ms)。既定は現在。
maxinteger 1..300任意1回の応答に含める最大対局数で、1~300。既定は100。
gamesarray任意含めるゲーム(std、anti、octagon、grand、reversi)。既定はすべて。
orderstring asc | desc任意asc: 古い順(既定)。desc: 新しい順。

リクエスト例

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}'

レスポンス例

{
    "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]
        }
    ]
}

対局記録

対局記録(record)は、終了した1対局を表すJSONオブジェクト1つです。対局者、結果、レーティング、開始の手、各手の時刻を、自分のボットの側から記録します。同じオブジェクトを2か所で受け取れます。

  1. 対局終了イベント: 対局が終わると、最後のmatchイベント(status finishedまたはaborted)にrecordが入ります。
  2. agent_games: 終了した対局を1行に1対局ずつ返します。過去の対局や受け取り損ねた対局の取得に使います。

手順はサイトの棋譜表記で書きます。1手は2文字で、パスはpaです。列はa~j、行は1~9で、10×10の10行目は0です(j0はマス99)。squaresは同じ手をマス番号で表し(パスは-1)、colorsは各手を打った側をBまたはWで表します。

ストリームが切れている間に終わった対局と、対局記録の準備がまだの人との対局では、対局終了イベントにrecordが入りません。この抜けは、次の手順でagent_gamesを使って埋めます。

  1. 開始点: 保存済みの最新の対局記録のupdated_msをsinceとして送ります。sinceはその時刻を含むので、最後の対局記録がもう一度届きます。
  2. 重複を飛ばす: kindとidがすでに持っているものと同じ対局記録は飛ばします。
  3. 次のページ: 受け取った最新のupdated_msで、もう一度呼び出します。新しい対局記録がない応答が来たら止めます。
  4. 変更された対局記録: 技術的な無効のように終了後に変わった対局は、より新しいupdated_msでもう一度届きます。古い対局記録を、届いたもので置き換えてください。

agent_games

対局記録のフィールド
フィールド型説明
formatinteger対局記録の形式の版番号で、現在は1です。版1にも新しいフィールドが加わることがあり、番号が上がるのは既存のフィールドの意味が変わるときだけです。
kindstringbot: 2局で行うボット同士の対局。human: 1局で行う人との対局。
idintegerkind botならボット同士の対局のID、kind humanなら対局IDです。kindとidの組で対局記録を1つに特定します。
urlstring対局を再生するページ
room_id, round_nointeger | null人との対局のみ: 対局室とラウンド
game_modestringゲーム(std、anti、grand、octagon、reversi)
opening_modestringrandom12: ボット同士の対局のランダムな12石の開始。xotまたはstd: 人との対局の始まり方。
board_sizeinteger 8 | 10盤の1辺のマス数、8または10
time_limit_secinteger局ごと、色ごとの持ち時間(秒)
autoboolean自動マッチングで作成
rankedbooleanレーティング対戦かどうか
rating_appliedboolean結果がレーティングに反映されたか
statusstringfinished、技術的な無効ならaborted
finish_reasonstring | null終局の理由: ボット同士の対局はstate.finish_reasonと同じ値、人との対局は対局室の値。
resultstring自分のボット側から見たwin、loss、drawまたはvoid
started_ms, finished_ms, updated_msinteger | null開始と終了の時刻(ms)で、人との対局ではstarted_msはnullです。updated_msは対局記録が最後に変わった時刻(通常は終了時刻)で、sinceとuntilはこの値と比べます。
meobject自分のボット: bot_id、name、engine、rating_before、rating_after。engineは開始時に報告したエンジン名で、レーティングに反映されない対局では両方のレーティングがnullです。
opponentobject相手: kind(bot、humanまたはguest)、name、engine、rating_before、rating_after。ボットにはさらにbot_idとbuiltin、人にはplayer_idがあります。
discs[integer, integer]自分のボットと相手のスコア: ボット同士の対局は両局の合計(state.totals)、人との対局は石数。
opening, opening_squares, opening_colorsstring, integer[], string各局の前の開始の手(同じ表記)で、ランダムな12石の開始またはXOTの開始局面です。
legs[].my_colorstringこの局での自分のボットの色、BまたはW
legs[].statusstringactive, finished, timeout, stopped
legs[].discs[integer, integer]色の順(黒、白)の石数
legs[].result_discs[integer, integer] (optional)時間切れになった局の合計用の判定点[黒, 白](任意のフィールド)。ある場合はdiscsの代わりに合計します。時間切れ側と相手の点数はstdとreversiが0対64、grandが0対100、octagonが0対88、antiが64対0です。もう一方の局は続き、両局が終わったあと合計で勝敗を決めます。過去の終了済みの記録は再計算しません。
legs[].moves, squares, colorsstring, integer[], string開始の手の後のこの局の手順: movesは文字列、squaresはマス番号、colorsは各手のBまたはW。
legs[].at_ms, used_ms, left_ms(integer | null)[]各手について、打った時刻(ms)、使った時間、着手後に打った側に残った持ち時間です。人との対局では打った時刻がnullで、不明な値もnullです。
legs[].evals(number | null)[] (optional)各手で打った側が送った評価値で、打った側から見た石数です。評価値なしで打った手は null です。その局に評価値が一つもなければ、このフィールドはありません。

エラー処理

エラーは{"ok": false, "error": "…"}の形式です。401は停止してトークンを確認します。409は手元の最新の状態で手番、revision、合法手を確認します(不確かならストリームを再接続)。410は廃止された動作です(2026-11-22 00:00 (UTC+9) からのagent_poll)。イベントストリームを使ってください。429はリクエストが多すぎることを示します(bot_match_api.phpへ1つのボットが毎秒20回、同じIPのボット合計で毎秒40回を超える)。429、5xx、接続エラーは0.2〜0.5秒後に同じリクエストを再送し(Retry-Afterがあれば従う)、数回後から間隔を延ばしてください。不正な着手は再送しないでください。

{"ok":false,"error":"stale_revision","server_now_ms":1800000000000}
HTTPerror
400JSON object required / unknown action
401invalid bot credential
403access denied / invalid csrf
405POST required
409stale_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
410agent_poll was removed; use bot-stream
413request too large
429Too many requests (bot_match_api.php rate limit)
503bot match storage unavailable

agent_poll
状態を取得(2026-11-22 廃止)

2026-11-22 00:00 (UTC+9) に廃止されます。以後はHTTP 410 {"ok": false, "error": "agent_poll was removed; use bot-stream"} を返します。状態はイベントストリームで受け取り、同期し直すときはストリームを再接続してください。それまでは応答しますが、2026-11-21 23:40 (UTC+9) から、直近10分間に使った登録ボットは自動マッチングから外れます。

APIを直接実装する場合
Copyright © Othelloclubthe.othelloclub.com@gmail.com All rights reserved.