API-dokumentation

Trin-for-trin-guide for begyndere

Det skal du bruge

  • En konto på FlipSight.
  • Ét botbillede: en GIF-, JPG- eller PNG-fil på højst 5 MB og mindst 175 px i både bredde og højde.
  • Din egen computer til at køre botten Din bots træk beregnes på den computer, hvor forbindelsesprogrammet kører. Selv med samme motor kan styrken variere med computerens ydeevne og motorens indstillinger, og hvis du skifter computer eller indstillinger, kan ratingen flytte sig tilsvarende.
  • Python 3, et gratis program, der kører forbindelsesprogrammet. Version 3.9 eller nyere virker; 3.11 eller nyere anbefales. Du tjekker det i trin 5.
  • Din bots motor. Forbindelsesprogrammet indeholder en øvelsesmotor til test.

1. Registrer din bot

Log ind, og åbn botsiden (othelloclub.com/da/flipsight/lab). I boksen Registrer min bot øverst skriver du et navn i Botnavn (2–24 tegn). Lad indtil videre kun Standard være markeret under Understøttede spil. Vælg et billede under Upload botfoto, og tryk derefter på knappen Registrer min bot.

Sådan ser det ud, når det lykkes: boksen Forbindelsestoken (vises kun én gang) vises med en lang tekst, der starter med fsbm_.

2. Gem din token

Den lange tekst er din token, en adgangskode kun til din bot. Forbindelsesprogrammet bruger den til at bevise over for serveren, at det taler på vegne af denne bot. Kopier hele teksten, og indsæt den et midlertidigt sted, for eksempel i et tekstredigeringsprogram. Når du har lukket boksen, kan du ikke se den samme token igen.

Behandl din token som en adgangskode. Vis den ikke til nogen, og del ikke skærmbilleder af den. Hvis du mister den, eller andre ser den, så åbn Administrer i botlisten, og tryk på Udsted forbindelsestoken. Når du får en ny token, holder den gamle op med at virke med det samme.

3. Hent forbindelsesprogrammet

Tryk på Hent Python-eksempler for at hente ZIP-filen, og pak den ud. I denne guide kaldes den udpakkede mappe "botmappen". Læg den et sted, hvor den er nem at finde, for eksempel på skrivebordet.

Sådan ser det ud, når det lykkes: botmappen indeholder filen README.md og mappen tools.

4. Åbn en terminal i botmappen

En terminal er et vindue, hvor du skriver kommandoer. Åbn den sådan her på dit system.

macOS: tryk på Command+Space, skriv Terminal, og åbn programmet. Skriv cd og et mellemrum, træk botmappen ind i vinduet, og tryk på Enter.

Linux: højreklik på botmappen i filhåndteringen, og vælg Åbn i terminal. Menunavnet kan være forskelligt fra distribution til distribution. Hvis menuen ikke findes, så åbn en terminal, og brug cd som på macOS.

Windows: åbn botmappen i Stifinder. Skriv powershell i adresselinjen øverst, og tryk på Enter. Et PowerShell-vindue åbner i den mappe.

Tjek: skriv kommandoen nedenfor, og tryk på Enter. Det er lykkedes, hvis README.md og tools står på listen. Kommandoen er den samme på macOS, Linux og Windows PowerShell.

ls

5. Tjek Python

I samme vindue kopierer du den ene kommando til dit system, indsætter den og trykker på Enter. Du kan bruge kopieringsknappen øverst til højre i hver kodeboks.

macOS / Linux

python3 --version

Windows PowerShell

py --version

Sådan ser det ud, når det lykkes: en version, der starter med 3, for eksempel Python 3.11.9. Version 3.9 eller nyere virker. Hvis kommandoen ikke findes, så installer Python som beskrevet nedenfor, luk vinduet, og start forfra fra trin 4.

macOS: hent installationsprogrammet til macOS (.pkg) fra python.org, og installer det. Kør derefter Install Certificates.command én gang fra Python-mappen under Programmer. Det klargør de certifikater, der skal bruges til sikre forbindelser (HTTPS).

Linux: installer python3 med din distributions softwarecenter eller pakkehåndtering.

Windows: installer Python install manager fra python.org.

python.org

6. Indtast din token

Læg din token i en miljøvariabel, en midlertidig indstilling, der kun findes i dette terminalvindue. Den hedder FS_BOT_TOKEN. Kopier kommandoen på én linje til dit system nedenfor, indsæt den, og tryk én gang på Enter. Så vises Bot token og venter på dit input. Indsæt nu den token, du kopierede i trin 2, og tryk på 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

På macOS og Linux vises den indsatte token ikke, og på Windows ser du * i stedet for tegnene. Begge dele er normalt. Fordi din token ikke skrives ind i kommandoen, bliver den ikke gemt i kommandohistorikken. Indstillingen gælder kun i dette vindue. Hvis du har lukket det eller åbnet et nyt vindue, så gentag trin 4 og 6.

Indsæt tokenet i PowerShell med Ctrl+V.

Sådan ser det ud, når det lykkes: prompten til den næste kommando kommer tilbage uden fejl.

7. Start forbindelsesprogrammet

I samme vindue kopierer du kommandoen nedenfor, som den er, indsætter den og trykker på Enter. Ændr ikke filnavnene i den. Din bot forbinder sig med øvelsesmotoren, en meget svag motor, der spiller det lovlige felt med det laveste nummer.

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'

Det er normalt, at kommandoen ikke viser tekst eller vender tilbage til prompten, mens den kører. Hold denne rude åben med forbindelsesprogrammet og motoren kørende, og undgå, at computeren går i dvale, for at holde din bot online. Hvis du lukker ruden eller trykker Ctrl+C, stopper begge programmer, og din bot går offline. Kør kommandoen ovenfor igen for at få den online. Forbindelsesprogrammet accepterer automatisk udfordringer fra andre botter.

Så længe botten kører med øvelsesmotoren, får den ingen automatiske kampe, og dens kampe mod andre bots, også dem du selv anmoder om, er ikke ratede. Start den igen med din egen motor (trin 10), så bliver den parret og ratet fra da af.

Sådan ser det ud, når det lykkes: i listen Registrerede bots på botsiden er prikken til højre for din bots navn grøn. Holder du musen over den, vises Online.

8. Test med en første kamp

Vælg din bot under Min spillende bot på botsiden. Vælg en vilkårlig bot på listen FlipSight-bots, tryk på Udfordr, og bekræft i det vindue, der åbner. I alle spiltyper beregner serveren trækkene for FlipSight-bots, så du behøver ikke holde spillerummet åbent.

Sådan ser det ud, når det lykkes: spillerummet viser to brætter, og der lægges en brik, hver gang det er din bots tur. Øvelsesmotoren er meget svag, så det er normalt at tabe.

9. Lad den køre, når vinduet er lukket (valgfrit)

Stop forbindelsesprogrammet med Ctrl+C i vinduet fra trin 7 efter det første parti. Start det igen dér med kommandoen nedenfor. Hold computeren vågen.

macOS / Linux

Brug screen, og erstat mybot med et særskilt navn for hver bot. Tryk Ctrl+A og derefter D efter start. Nu kan du lukke vinduet. Gå tilbage til sessionen med den nederste kommando, og tryk Ctrl+C for at stoppe botten.

Start

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

Stop

screen -r mybot

Windows PowerShell

Windows: et minimeret vindue vises på proceslinjen, og botten kører i det. Du kan lukke det nuværende PowerShell-vindue. For at stoppe den åbner du det minimerede vindue og trykker på Ctrl+C eller lukker vinduet.

Start

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. Skift til din egen motor

Efter forbindelsestesten skiftes til din egen motor: de særlige indstillinger nedenfor til Edax eller Egaroucid, --nboard til andre kompatible motorer, JSON til din egen motor. Behold samme token.

Markér kun en variant (Anti, 10x10, Octagon, klassisk Reversi) under Understøttede spil, hvis din motor kender reglerne for den. Andre bots og mennesker kan udfordre din bot i alle markerede spil. For at ændre det åbner du Administrer i botlisten, retter Understøttede spil og trykker på Gem. Du kan ikke ændre det, mens en kamp er i gang eller en udfordring venter.

Almindelige problemer

SymptomÅrsag og løsning
Botten har en grå prik (offline).Tjek, at vinduet med forbindelsesprogrammet stadig kører. Det stopper, når du lukker vinduet, trykker på Ctrl+C, eller computeren går i dvale.
Der står, at kommandoen ikke blev fundet.
command not found / is not recognized
Python mangler, eller vinduet blev ikke åbnet igen efter installationen. Se trin 5, åbn et nyt vindue, og start forfra fra trin 4.
Der står, at filen ikke kan åbnes.
can't open file
Du kørte kommandoen uden for botmappen. Gå til botmappen som i trin 4, og tjek med ls, at README.md og tools står på listen.
Der står, at token mangler, og programmet afslutter.
FS_BOT_TOKEN is missing or invalid
Dette vindue har ingen token. Hvis du har åbnet et nyt vindue, så gentag trin 6.
Der står, at token blev afvist, og programmet stopper.
Bot credential rejected
Din token blev indsat forkert eller er en gammel. Når du har udstedt en ny token eller deaktiveret botten, virker den gamle token ikke længere. Start forfra fra trin 6 med den nyeste token.
Den samme fejllinje bliver ved med at komme.
Connection/state error
Tjek internetforbindelsen. På macOS skal du tjekke, at du har kørt Install Certificates.command fra trin 5. Hvis fejlen kun kommer under kampe, afviser serveren måske din motors træk som ulovligt. Forbindelsesprogrammet sender det samme træk igen, så motoren skal rettes.
Udfordringsknappen virker ikke, eller udfordringen bliver ikke accepteret.Vælg Min spillende bot, og tjek at begge botter er online. Modstanderen skal tage imod direkte udfordringer og have en ledig plads. En ubesvaret udfordring udløber efter 120 sekunder.
Botten spiller intet træk og taber derefter på tid, eller kampen annulleres.
Engine failed for match
Motoren svarede ikke i tide, eller svaret havde forkert format. Tjek motorkommandoen og dens JSON-output på én linje. Hvis en bot ikke spiller sit første træk inden for 30 sekunder efter start, annulleres kampen.
Der kommer ingen udfordringer i varianter.Udfordringsvinduet viser kun spil, som begge bots understøtter. Tjek, at spillet er markeret under Understøttede spil for din bot, og at den anden bot også understøtter det. En bot, der er forbundet via --edax eller --nboard, bør kun have Standard markeret.

Ordliste

BegrebBetydning
APIEn aftalt måde, hvorpå programmer sender forespørgsler og svar. Forbindelsesprogrammet klarer det for dig.
TokenEn adgangskode kun til din bot. Forbindelsesprogrammet bruger den til at bevise over for serveren, hvilken bot det er.
TerminalEt vindue, hvor du skriver kommandoer. På Windows bruger du PowerShell.
MiljøvariabelEn midlertidig indstilling, der gives videre til programmer, som startes fra ét terminalvindue. Den forsvinder, når vinduet lukkes.
JSONEt format til at skrive data som tekst. Eksempel: {"move":19}
MotorEt program, der ser på en stilling og vælger et træk.
AdapterEt lille program, der omsætter data mellem din motor og forbindelsesprogrammet.
NBoardEt åbent format, som Othello-motorer og brætprogrammer bruger til at udveksle stillinger og træk. Motorer, der understøtter det, som NTest, kan tilsluttes uden adapter.
Lovligt trækEt felt, du må spille på nu. Serveren lister dem i legal_moves.

Tilslut din motor

Brug højst 4 tråde pr. motor. En botkamp har to samtidige partier og bruger højst 8 tråde i alt.

Edax: --edax

Installations- og starteksemplerne nedenfor bruger Edax 4.6 og Egaroucid for Console 7.8.2.

Edax 4.6 følger ikke med forbindelsesprogrammet. Hent filen til dit styresystem under Assets på Edax 4.6, læg den i botmappen, og pak den ud med forberedelseskommandoerne nedenfor. Windows- og Linux-kommandoerne er til x86-64.

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

Forberedelse (kun første gang)

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

Start

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

Forberedelse (kun første gang)

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

Start

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

macOS: edax-reversi-4.6.tar.gz

Der findes ingen officiel macOS-programfil til Edax 4.6. Hent Source code (tar.gz) og edax-4.6-linux-x86.tar.gz fra samme udgivelse. Byg Mac-programmet fra kildekoden; hent kun den fælles vurderingsfil data/eval.dat fra Linux-arkivet. Xcode Command Line Tools kræves. Forberedelseskommandoerne kompilerer kildekoden.

Forberedelse (kun første gang)

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)

Start

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

Edax kan også forbindes med kun programstien via --edax nedenfor. Der kræves ingen separat adapter. Forbindelsesprogrammet starter Edax via xboard og sender begge resterende tider før hvert træk; Edax bestemmer selv sin tænketid ud fra sit ur (forbindelsesprogram v1.4.8 eller nyere). Under kampen beholder Edax spilforløbet og sin hashtabel, og med --engine-ponder on søger den også i modstanderens tid. --edax-protocol nboard bruger den tidligere NBoard-forbindelse.

Erstat stien i kommandoen med den fulde sti til din programfil. Sæt stier med mellemrum i dobbelte anførselstegn. Findes evalueringsfilen ikke automatisk, angives eval.dat med --edax-eval.

En forbindelse med --edax eller --nboard spiller kun standardkampe på 8×8. Lad kun Standard være markeret under Understøttede spil for denne bot. Hvis der kommer en variant, spørger forbindelsesprogrammet ikke motoren, der spilles intet træk, og kampen annulleres eller tabes på tid.

Egaroucid: --egaroucid

Klargør Egaroucid for Console. Vælg konsolprogrammet, og lad resources-mappen blive på sin plads. På macOS og Linux bruges et program bygget efter den officielle vejledning. Stillingen og resttiden sendes via setboard, settime og go uden en adapter.

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"

Begge tilstande understøtter kun standard 8×8, med én motor pr. samtidigt parti. --max-think-seconds er sikkerhedsgrænsen pr. træk (som standard 10 sekunder). Når Egaroucid når grænsen, stoppes søgningen, et lovligt reservetræk spilles, og motoren genstartes ved næste tur.

NBoard-motorer som NTest: --nboard

NBoard er et grafisk Othello-program, som kan bruges med NTest. NBoard-protokollen er programmets offentlige kommunikationsformat til motorer; motorer, der understøtter den, såsom NTest, tilsluttes med --nboard. Der holdes én motor kørende pr. kamp. Edax understøtter den også, men tilslut Edax med --edax ovenfor.

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"

En forbindelse med --edax eller --nboard spiller kun standardkampe på 8×8. Lad kun Standard være markeret under Understøttede spil for denne bot. Hvis der kommer en variant, spørger forbindelsesprogrammet ikke motoren, der spilles intet træk, og kampen annulleres eller tabes på tid.

Egen motor: forbind via JSON

Læs kun denne del, hvis du vil tilslutte en motor, du selv har skrevet. Hvis du bruger Edax, Egaroucid eller en NBoard-motor, er du allerede færdig ovenfor og kan springe den over.

Hver gang det er din bots tur, kører forbindelsesprogrammet my_adapter.py én gang. Det afleverer den aktuelle stilling som én linje (hvor brikkerne står, hvis tur det er, hvilke felter der er lovlige, hvor meget tid der er tilbage), my_adapter.py svarer med ét felt som én linje, og forbindelsesprogrammet spiller det træk på serveren. my_adapter.py er en lille Python-fil i midten, som beder din motor om trækket. Forbindelsesprogrammet tager sig af forbindelsen til serveren, din token og indsendelsen af træk, så denne fil skal aldrig tage sig af det.

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

Hvilken slags motor har du?

  • En motor, der vælger sit træk i Python-kode: brug eksempel A nedenfor.
  • En programfil, der udskriver én svarlinje og afslutter, hver gang den køres: brug eksempel B nedenfor.
  • En programfil, der forbliver åben og løbende udveksler kommandoer: understøtter den NBoard, så tilslut den med --nboard ovenfor. Ved en anden protokol tilpasser du eksempel B til protokollen og lader my_adapter.py holde motoren åben og udveksle én linje ad gangen i en løkke.

Trin 1: en fil, der kun tjekker forbindelsen (my_adapter.py)

Opret en fil med navnet my_adapter.py i botmappen (hvor README.md og tools ligger), indsæt koden nedenfor, som den er, og gem filen. Denne fil bruger ingen motor og svarer bare med det første lovlige felt. Den er der, så du kan se, at forbindelsen virker, før du tilslutter din motor.

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)

Tjek input og output, før du forbinder

Kommandoen i boks 1 sender eksempelstillingen direkte ind i adapteren. Den skal udskrive én linje: {"move": 19}. Når du ser den linje, starter kommandoen i boks 2 forbindelsesprogrammet med denne adapter i det vindue, der har din token fra trin 6. Kør de to bokse hver for sig. Hvis din motor selv kan læse dette JSON-format, kan du sætte dens kommando direkte efter --engine.

1. Test adapteren alene

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. Start forbindelsesprogrammet med adapteren

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'

Trin 2: skift til en fil, der kalder din motor

Når trin 1 virker, erstatter du hele indholdet af my_adapter.py med eksempel A eller B nedenfor. Ret kun de linjer, der er mærket EDIT, og lad resten være, som det er. Kør derefter testkommando 1 ovenfor igen, og tjek, at der kommer én svarlinje. Det er din motor, der har valgt trækket, så et andet felt end 19 er helt normalt.

Eksempel A: en motor, der vælger sit træk med en Python-funktion

Dette eksempel forudsætter en fil med navnet my_engine.py med en funktion search, der vælger trækket. Ret filnavnet og funktionsnavnet ved EDIT 1 og de værdier, der sendes med, ved EDIT 2, så de passer til din motor. Funktionen skal returnere feltets nummer (0 til 63) eller en koordinat som 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)
Eksempel B: en motor, der er en programfil

Dette eksempel forudsætter, at programmet læser én linje med 64 brættegn, den side, der er i trækket, og betænkningstiden i millisekunder, og svarer med én koordinatlinje som D3 (. = tomt, X = sort, O = hvid). Hver motor har sit eget format, så ret programfilens navn ved EDIT 1, den linje, der sendes til motoren, ved EDIT 2 og den del, der læser svaret, ved EDIT 3, så det passer til din motor.

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)

Betænkningstid: i botpartier har hver bot 1 minut i hvert parti, så lang betænkningstid på et enkelt træk fører hurtigt til tab på tid. think_ms i eksemplerne deler den resterende tid (remaining_ms) med antallet af træk, du har tilbage, og finder på den måde tiden til dette træk. budget_ms er ikke den tid, der skal bruges på dette træk. Det er den længste tid, forbindelsesprogrammet venter på svaret (10 sekunder som standard). Kommer svaret senere end det, kan botten ikke fortsætte i det parti og taber det på tid, så giv din motor think_ms og ikke budget_ms.

Når noget går galt: hvis kaldet til motoren mislykkes, skriver eksempelfilerne årsagen i my_adapter.log og spiller det første lovlige felt i stedet. Hvis trækkene ser mærkelige ud, så åbn den fil først. Forbindelsesprogrammet viser ikke adapterens fejlmeddelelser på skærmen. Brug kun print til den ene svarlinje, og skriv al fejlsøgningstekst til en fil.

Hastighed: forbinderen holder my_adapter.py kørende for hvert parti og sender én linje pr. træk. En fil, der svarer én linje og afslutter, som eksemplerne, startes igen ved næste træk, så din motor starter også forfra hver gang. Er motoren langsom til at starte eller skal den bevare arbejdet fra tidligere træk, så gør my_adapter.py til en løkke: læs én linje, svar én linje, gentag. Læs ikke input til ende, og flush efter hvert svar.

Resten af denne del er opslagsstof om, hvad forbindelsesprogrammet og my_adapter.py udveksler. Hvis du bruger eksempelfilerne ovenfor, som de er, behøver du ikke læse det.

Input-JSON (forbindelsesprogram → adapter)

Dette er eksempeldata fra forbindelsesprogrammet, ikke kode, der skal køres. Gem dem ikke som en Python-fil. Under spillet sendes de aktuelle data automatisk for hvert træk.

Herunder er et eksempel på standardstartstillingen på 8×8. I rigtige partier udfylder forbindelsesprogrammet den aktuelle stilling. board lister felterne fra a1 mod højre og derefter næste række; 0=tomt, 1=sort, 2=hvid. color=1 beder om et træk for sort. legal_moves lister de felter, du må spille på. remaining_ms er den resterende tid på uret, og budget_ms er den længste tid, forbindelsesprogrammet venter på svaret på dette træk, begge i millisekunder (1000 = 1 sekund). Felter og eksempler for varianter står i afsnittet om varianter nedenfor.

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

Svar-JSON (adapter → forbindelsesprogram)

Skriv et af svarene nedenfor som én JSON-linje, der slutter med et linjeskift. move er et feltnummer eller en koordinat, uanset store og små bogstaver. På 8×8 er d3 (3−1)×8+3 = 19. Vælg altid blandt de legal_moves, du har modtaget. I botpar uden lovligt træk sender du -1 eller pass; i kampe mod mennesker afgør serveren tvungne pas. Skriv kun svarlinjen til stdout, uden andre beskeder.

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

Valgfrit: tilføj environment i svaret for at rapportere motorens faktiske tråde, hashstørrelse i MB og ponder (forbindelsesprogram v1.4.6 eller nyere). Forbindelsesprogrammet tager kun tal inden for grænserne og true/false og viser dem i botinformationen. Tilføjer din egen adapter eval, sender forbindelsesprogrammet den med trækket i kampe mellem bots (for eksempel {"move":19,"eval":1.5}). eval er din vurdering efter trækket i brikker set fra din side, højst spillets spillelige felter; --edax, --egaroucid og NBoard-motorer sender den selv efter opdatering til v1.5.3.

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

Eksempler på motorforespørgsler pr. spil

Downloads

Hent Python-eksempler

GitHub: flipsight-othello-bot-connector

OpenAPI 3.1 JSON

README.md

.zip indeholder vejledning, forbindelsesprogram og eksempelmotor; .json er API-specifikationen og .md er vejledningen.

Implementer API'et selv

Stop først træningsbottens forbindelsesprogram. Åbn strømmen med tokenet fra trin 6. Hold én forbindelse åben pr. token. Hver linje indeholder én JSON-hændelse.

Hændelsesstrøm

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"

Efter hello kommer state. Eksemplet viser de relevante felter for din bot med nummer 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]
                    }
                ]
            }
        }
    ]
}

Din bot spiller sort (1) på det andet bræt (leg 1). Når turn er 1, vælger du et træk fra legal_moves og sender det sammen med brættets revision. Når du spiller, skal du angive tokenet i en anden terminal som i trin 6 og bruge værdierne fra det aktuelle parti.

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

Hændelsesstrøm

Implementer API'et selv

TypeBeskrivelse
helloForbindelsen er oprettet. bot_id er din bots nummer.
stateErstat listen over aktive partier og invitationer. Er du bot_b, kan du acceptere en pending-invitation med agent_accept.
matchOpdater partiet med dette id. Tjek på hvert aktivt bræt, om det er din bots tur.
pingLivstegn hvert 10. sekund. Du behøver ikke svare.
closingSidste linje, før serveren lukker strømmen. Er reason overflow (for mange usendte linjer) eller server_shutdown, så forbind igen og indhent med state. replaced betyder, at samme token bruges et andet sted. Forbind ikke igen med det samme: vent mindst 30 sekunder, og længere hvis det sker igen. Brug hvert token kun ét sted.
Kampobjekt (matches[])
FeltTypeBeskrivelse
idintegerKamp-ID (negativt for partier mod et menneske)
kindstringhuman for partier mod et menneske
bot_aintegerBot-ID for deltager 0 (0 for et menneske)
bot_bintegerBot-ID for deltager 1 (0 for et menneske)
game_modestringSpil (std, anti, grand, octagon, reversi)
time_limit_secintegerSekunder pr. parti, pr. farve
statusstringpending, running, finished, aborted, rejected, expired
expires_msintegerFrist for accept (millisekunder)
rankedbooleanOm kampen er ratet
state.statusstringactive, finished eller aborted
state.game_modestringSpil (std, anti, grand, octagon, reversi)
state.board_sizeinteger 8 | 10Felter pr. side, 8 eller 10
state.blocked_squaresinteger[]Ubrugelige felter (kun Octagon, ikke sorteret)
state.legsarrayPartier (2 mellem bots, 1 mod et menneske)
state.totals[integer, integer]Brikker i alt fra begge partier pr. deltager
state.winnerinteger | nullVindende deltager 0 eller 1, null ved remis
state.finish_reasonstring | nulldiscs, timeout, double_timeout, disconnect, no_first_move
Partiobjekt (state.legs[])
FeltTypeBeskrivelse
boardinteger[64 | 100]64 / 100 felter, 0=tomt 1=sort 2=hvid
turnintegerFarven i trækket, 1 (sort) eller 2 (hvid)
legal_movesinteger[]Lovlige felter for farven i trækket. Tom for afsluttede partier
placed{"1": integer, "2": integer}Lagte brikker pr. farve, nøgler "1" (sort) og "2" (hvid)
black_participantintegerDeltageren, der spiller sort i dette parti
clocks_ms[number, number]Basisværdier for resterende tid i farveorden (sort, hvid)
turn_started_msintegerServertid, da den aktuelle tur begyndte
revisionintegerStiger med 1, hver gang dette parti ændres
statusstringactive, finished, timeout, stopped
historyarraySpillede træk (color, participant, move, at_ms, eval)
discs[integer, integer]Antal brikker i farveorden (sort, hvid)
result_discs[integer, integer] (optional)Valgfri tildelt score [sort, hvid] for et parti tabt på tid; læg den sammen i stedet for brikkerne. Score for den side, der løb tør for tid, og for modstanderen: std og reversi 0 til 64, grand 0 til 100, octagon 0 til 88, anti 64 til 0. Det andet parti fortsætter, og summerne afgør vinderen, når begge partier er slut. Ældre afsluttede registreringer genberegnes ikke.

Når et spil slutter, har den sidste match-hændelse også record, spilprotokollen, med. Gem den, som den er, for at beholde hele spillet. Spilprotokoller

Statussynkronisering

Hvis forbindelsen afbrydes, eller du intet modtager i 15 sekunder, så forbind igen med stigende ventetid fra 1 til 30 sekunder. Kassér ældre tilstande. Mod en person sammenlignes room_created_at, round_no og revision i den rækkefølge. Send kun et træk igen efter et mistet svar, hvis det stadig er din tur og brættets revision er den samme.

Send motoroplysninger med agent_environment ved start og ved ændringer. Til automatisk matchning tillader v2 højst 10 strømforbindelser og ingen kald til agent_poll i de seneste 10 minutter online.

Godkendelse

Brug HTTPS, JSON POST og Authorization: Bearer. Token gælder kun én bot. Skriv den aldrig i URL’er, offentlig kode eller logs.

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

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

Indstillinger for forbindelsesprogrammet

Indstillinger for tools/bot_match_client.py. Præcis én af --engine og --nboard / --edax / --egaroucid er påkrævet. Token er aldrig en indstilling; den læses kun fra miljøvariablen FS_BOT_TOKEN. Afslutningskoder: 0 normalt stop, 2 token afvist, 3 --max-runtime nået.

ParametreBeskrivelse
--engine "COMMAND"Starter denne kommando én gang pr. parti og udveksler én JSON-linje pr. træk uden at lukke dens input. En motor, der svarer én linje og afslutter, startes igen ved næste træk.
--nboard "COMMAND"Beholder én NBoard-motor pr. parti, to i alt. Kun standard (std).
--edax PATHEdax kan også forbindes med kun programstien via --edax nedenfor. Der kræves ingen separat adapter. Forbindelsesprogrammet starter Edax via xboard og sender begge resterende tider før hvert træk; Edax bestemmer selv sin tænketid ud fra sit ur (forbindelsesprogram v1.4.8 eller nyere). Under kampen beholder Edax spilforløbet og sin hashtabel, og med --engine-ponder on søger den også i modstanderens tid. --edax-protocol nboard bruger den tidligere NBoard-forbindelse.
--edax-eval PATHSti til Edax eval.dat. Uden angivelse søges efter data/eval.dat i programmappen eller dens overordnede mappe.
--edax-protocol xboard|nboardForbindelsesmåde for --edax. Standarden xboard lader Edax styre sit eget ur og pondere (v1.4.8 eller nyere). nboard er forbindelsen til og med v1.4.7: forbindelsesprogrammet fastsætter tiden til hvert træk, og Edax ponderer ikke.
--egaroucid PATHKlargør Egaroucid for Console. Vælg konsolprogrammet, og lad resources-mappen blive på sin plads. På macOS og Linux bruges et program bygget efter den officielle vejledning. Stillingen og resttiden sendes via setboard, settime og go uden en adapter.
--egaroucid-level NBruges sammen med --egaroucid. 1 til 60 starter Egaroucid på det niveau (-level N) og sender ikke resterende tid (settime); 0 eller ingen værdi beholder tidstilstanden, der følger spilleuret. Niveautilstanden har ingen kommando til at stoppe en søgning undervejs: hvis et træk går over grænsen i --max-think-seconds, stopper forbindelsesprogrammet motoren og spiller et lovligt nødtræk. Vælg et niveau, der bliver færdigt med god margin inden for spilleuret.
--nboard-depth NSender set depth N til NBoard-motoren. 0 til 60; 0 beholder motorens standard. Med --edax er det Edax-niveauet (20 betyder L20); uden værdi er niveauet 60. Edax spiller det bedste træk indtil da, når niveauet er nået, eller tiden til trækket er brugt, alt efter hvad der kommer først. Med --edax sendes værdien via xboard som sd N.
--max-think-seconds SDet maksimale antal sekunder, der ventes på motoren pr. træk. Standard 10, maksimum 300. Aldrig længere end den resterende tid på uret minus 0,75 sekunder. Det er en sikkerhedsgrænse i forbindelsesprogrammet; serveren har ingen tidsgrænse pr. træk. Med 0 fjernes grænsen pr. træk, og den resterende spilletid bruges. Spilleuret fastsættes af siden, og forbindelsesprogrammet kan ikke ændre det: kampe mellem bots og automatiske botkampe giver hver farve 60 sekunder pr. bræt, og en person, der udfordrer din bot direkte, vælger tiden. Med --edax bestemmer Edax selv tiden til hvert træk ud fra sit ur inden for denne grænse; nås grænsen, får forbindelsesprogrammet Edax til straks at spille det bedste træk indtil da.
--engine-name NAMEMotornavn, der vises i botoplysningerne (højst 120 tegn). Medtag ikke kommandoer eller stier.
--engine-threads NAntal tråde motoren bruger pr. parti , vises i profilen. Med --edax eller --egaroucid kører motoren med denne værdi (standard 4, hvis computeren har flere end 4 logiske CPU’er, ellers 1); med --engine sendes den i hver forespørgsel som engine_threads. Brug højst 4 tråde pr. motor og 8 i alt pr. botkamp med to samtidige partier. Med --engine/--nboard bliver du spurgt, hvis værdien mangler; ved baggrundskørsel eller automatisk kørsel er denne indstilling påkrævet.
--engine-hash-mb MBHashtabellens størrelse pr. motor i MB. Med --edax eller --egaroucid sættes tabellen til den største potens af to, der ikke overstiger værdien (Edax -h, Egaroucid -hash), og den størrelse rapporteres; uden indstillingen bruger Edax edax.ini og Egaroucid 32 MB. Andre motorer rapporterer kun værdien, og deres indstilling ændres ikke. Hver motor har sin egen tabel, så et botparti med to spil på samme tid bruger det dobbelte.
--engine-ponder on|offPonder (søgning i modstanderens tid). Med --egaroucid starter on Egaroucid med -ponder og rapporterer Til; den bruger også CPU i modstanderens tur. Med --edax (forbindelsesprogram v1.4.8 eller nyere) får on Edax til at pondere via xboard (hard) og rapporterer Til; med --edax-protocol nboard ponderer Edax ikke, og on afvises. Andre motorer rapporterer kun deres faktiske indstilling.
--cpu-name NAMECPU-navn, der skal rapporteres (højst 120 tegn). Findes automatisk, hvis det udelades.
--once-match IDHåndterer kun denne kamp og afslutter, når den slutter (afsluttet, annulleret, udløbet, afvist). Negative id'er for kampe mod mennesker virker også. Til test kan du kombinere den med --max-runtime.
--max-runtime SRydder op i motorerne og afslutter efter dette antal sekunder (afslutningskode 3).
--save-games DIRGemmer hvert spil, der slutter, efter at indstillingen er slået til, i DIR/games-YYYY-MM.ndjson, én spilprotokol per linje (slået fra som standard). Spil, der sluttede, mens forbindelsesprogrammet var stoppet eller strømmen var nede, udfyldes med agent_games ved genforbindelse, fra det nyeste gemte spil. Et spil fylder cirka 4 KB (cirka 6 KB på 10×10), så 1.400 spil om dagen giver cirka 6 MB om dagen og 180 MB om måneden. Slet selv gamle månedsfiler, når du ikke længere har brug for dem.
--timing-log PATHTilføjer én linje pr. træk med, hvor tiden gik hen (modtage trækket, vente på en ledig søgning, motor, sende trækket). Slået fra som standard; der sendes ikke mere til serveren.
--api URL, --stream-url URLAdresser til API og strøm. Behold normalt standardværdierne. Kun HTTPS accepteres, og da din token sendes med, skal strømmen ligge på API-værten.

Varianter

En bot modtager kun de spil, der er markeret under Understøttede spil. game_mode i motorforespørgsler og kamptilstand fortæller, hvilket spil det er. Serveren beregner brætstørrelse, blokerede felter og lovlige felter, så motoren skal kun vælge blandt de legal_moves, den modtager. Generér ikke træk til 10×10 eller klassisk Reversi med trækgenerering til standard 8×8.

Spilgame_modeBræt
Standardstd8×8
Antianti8×8
Grand (10x10)grand10×10
Octagonoctagon10×10 (88)
Klassisk reversireversi8×8

Fælles regler: Sort (1) trækker først. Begge partier starter fra samme stilling med ombyttede farver og spilles samtidig. Hvis du i et botpar ikke har noget lovligt træk, kommer legal_moves som et tomt array, og botten skal selv sende move=-1 (pas). Serveren melder ikke pas for dig, og dit ur kører videre. Det er ulovligt at melde pas, når der findes et lovligt træk. Et parti slutter, når ingen af farverne kan trække. I nye dobbeltkampe lægges tomme felter i normalt afsluttede partier til farven med flest brikker, og begge resultater lægges sammen. I Anti vinder den laveste justerede sum; ved lige mange brikker fordeles ingen tomme felter. Lige samlede summer er remis. Alle botpartier starter fra en tilfældig stilling med 12 brikker. I alle spiltyper har hver bot 1 minut i hvert parti.

Anti: brikker lægges og vendes som i standard-Othello. Siden med færrest brikker samlet over begge partier vinder.

10x10: standardregler på et 10×10-bræt (100 felter). Startbrikkerne står på de fire midterfelter; botpar lægger 8 tilfældige træk til og starter med 12 brikker.

Octagon: samme bræt og startopstilling som 10x10, men tre felter i hvert hjørne, 12 i alt, kan ikke bruges (88 spilbare felter). Blokerede felter kommer som feltnumre i blocked_squares og som 0, samme værdi som tomt, i board. Arrayet er ikke i numerisk rækkefølge. Du kan ikke spille på et blokeret felt, og rækker af brikker stopper der.

Klassisk Reversi: starter ifølge reglerne på et tomt bræt. Så længe et af de fire midterfelter (27, 28, 35, 36) er tomt, lægger du kun der, og intet vendes. Når alle fire er fyldt, gælder standardreglerne. Hver farve lægger højst 32 brikker, inklusive de første fire træk. placed tæller de brikker, hver farve har lagt indtil nu; nøglerne er strengene "1" (sort) og "2" (hvid). Botpar starter, efter at serveren har lagt 12 tilfældige brikker, inklusive de fire midtertræk, så i den første forespørgsel giver de to placed-tal tilsammen 12 (normalt {"1":6,"2":6}). En farve, der har lagt alle 32, modtager en tom legal_moves og sender -1, hver gang det er dens tur.

Eksempler på motorforespørgsler pr. spil

Eksempler på den første forespørgsel for sort, som forbindelsesprogrammet sender til en motor med --engine, genereret med regelkoden. Rigtige kampe af alle typer starter fra en tilfældig stilling med 12 brikker, så board og legal_moves er forskellige i hver kamp. For at eksemplerne forbliver de samme, er deres åbningstræk valgt nær midten af brættet. match_id og urværdierne er også anderledes i rigtige kampe.

Anti (anti)

Input-JSON (forbindelsesprogram → adapter)

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

Svar-JSON (adapter → forbindelsesprogram)

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

Input-JSON (forbindelsesprogram → adapter)

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

Svar-JSON (adapter → forbindelsesprogram)

{"move":13}
Octagon (octagon)

Input-JSON (forbindelsesprogram → adapter)

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

Svar-JSON (adapter → forbindelsesprogram)

{"move":13}
Klassisk reversi (reversi)

Input-JSON (forbindelsesprogram → adapter)

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

Svar-JSON (adapter → forbindelsesprogram)

{"move":18}

Felter i motorforespørgslen

FeltTypeBeskrivelse
game_modestringEn af std, anti, grand, octagon, reversi. XOT i kampe mod mennesker kommer som std.
board_sizeinteger 8 | 108, eller 10 for grand og octagon.
boardinteger[board_size²]Array med længden board_size². Læses fra a1 mod højre og derefter næste række. 0=tomt (inklusive Octagons blokerede felter), 1=sort, 2=hvid.
blocked_squaresinteger[]Ubrugelige felter i Octagon. Et tomt array i andre spil.
placed{"1": integer, "2": integer}Brikker lagt indtil nu pr. farve, inklusive de tilfældige åbningstræk; nøglerne er strengene "1" og "2". Bruges til grænsen på 32 brikker i klassisk Reversi.
legal_movesinteger[]Felter, du må spille på nu. Hvis listen er tom, svarer du move=-1.
colorinteger 1 | 2Farven i trækket. 1=sort, 2=hvid.
budget_msintegerTilladt tid til dette træk i millisekunder: den mindste af --max-think-seconds og den resterende tid på uret minus 0,75 sekunder. Forbindelsesprogrammet stopper motoren, når den overskrides.
remaining_msintegerDin farves resterende tid i dette parti i millisekunder, efter at den tid, der allerede er brugt i denne tur, er trukket fra.
match_idinteger ≠ 0Kamp-id. Negativt (-rumnummer) for kampe mod mennesker.
leginteger 0 | 1Partinummer 0 eller 1. Altid 0 for kampe mod mennesker.
revisionintegerTilstandsnummer for dette parti. Send det uændret med agent_move.
historyarrayTræk spillet i dette parti. Træf beslutningen ud fra board.
round_nointeger | nullRundenummer i en kamp mod et menneske. null for botpar.
room_created_atstring | nullOprettelsestidspunkt for rummet til kampen mod et menneske. null for botpar.
engine_threadsinteger (optional)Findes kun, når forbindelsesprogrammet er startet med --engine-threads. Antal tråde motoren må bruge i dette parti; tilpas søgningen efter det.

Udfordr en anden bot til en variant

Tilføj game_mode til agent_challenge; standard er std. Begge bots skal have spillet i supported_games. Se modstanderens spil på botsiden. Hvis en af botterne mangler spillet, er svaret HTTP 409 med fejlen nedenfor.

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

Ændring af supported_games

Registreringsformularen starter med Standard markeret, og ældre bots uden en gemt liste understøtter std. Du kan kun ændre listen under Administrer på botsiden på nettet, aldrig med bottens token (API). Ændringen afvises, mens en kamp er i gang eller venter på accept. En tom liste kan ikke gemmes.

Mennesker mod registrerede bots

Mennesker kan udfordre din bot i ethvert spil, den har registreret. Hvis den understøtter standard, kan både STD og XOT komme. XOT kommer med game_mode std og starter fra et bræt, hvor 8 træk allerede er spillet (de er med i history). Den, der udfordrer, vælger uret, og kampen tæller ikke med i ratingen. En kamp mod et menneske har ét parti (leg 0) og et negativt match_id. Serveren håndterer pas, når der ikke er noget muligt træk, så send ikke -1. Registrerede botter online med automatisk parring slået til deltager også i understøttede STD/XOT-hurtigkampe. De er ratede for medlemmer og uratede for gæster.

Ulovlige træk og tid

Et ulovligt træk eller en forældet revision afvises med HTTP 409 (illegal_move, stale_revision, not_your_turn), og brættet ændres ikke. Uret kører imens videre. Forbindelsesprogrammet sender det samme træk igen med samme revision, så medmindre motoren rettes, tabes partiet til sidst på tid. Serveren har ingen grænse pr. træk og tjekker kun hver farves resterende tid. De 10 sekunder er forbindelsesprogrammets standardværdi for --max-think-seconds.

Kampregler

Alle botpartier starter fra en tilfældig stilling med 12 brikker. To partier spilles samtidig med ombyttede farver. Det samlede antal brikker afgør vinderen; i Anti vinder det laveste antal.

I alle spiltyper har hver bot 1 minut i hvert parti.

Har en bot ikke spillet sit første træk inden for 30 sekunder efter start, annulleres kampen og tæller ikke i rating. Mister en bot forbindelsen i mere end 30 sekunder under kampen, mens den anden er forbundet, vinder den forbundne bot (finish_reason: disconnect), og resultatet tæller i rating.

Serveren beregner FlipSight-bottens træk i alle spiltyper. Både udfordringer på nettet og via API’et (agent_challenge) modtages, og serveren starter kampen med det samme, så du behøver ikke holde spillerummet åbent. Hvis serverens beregning står stille i mere end 30 sekunder, annulleres kampen (finish_reason: technical) og ratingen påvirkes ikke. Varianter er tunge at beregne, så højst 2 variantkampe mod FlipSight-bots kører ad gangen. Er pladserne fyldt, får du HTTP 409 med site bot variant matches are full; prøv igen om lidt.

Automatisk matching parrer bots med højst 500 ratingpoint imellem sig i en variant, begge har valgt. Forbindelsesprogrammet har 120 sekunder til at acceptere. Resultatet tæller med i ratingen. Vælg varianter eller slå automatisk matching fra under Administrer. En bot, der er startet med øvelsesmotoren (environment.practice er true), holdes ude af automatiske kampe, og dens kampe mod andre bots i den tid er ikke ratede.

En direkte udfordring fra et menneske spilles som ét parti i et normalt rum med understøttet spil og tid. Serveren gør altid direkte udfordringer uratede. Registrerede botter online med automatisk parring slået til deltager også i understøttede STD/XOT-hurtigkampe. De er ratede for medlemmer og uratede for gæster. En registreret bot tager kun imod så mange partier, som dens indstilling for samtidige partier tillader (standard 2). Et parti mod et menneske og en botkamp (to brætter) tæller hver 1.

Kampforløb

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)

Alle botpartier starter fra en tilfældig stilling med 12 brikker. To partier spilles samtidig med ombyttede farver. Det samlede antal brikker afgør vinderen; i Anti vinder det laveste antal.

Dit deltagernummer er 0, hvis du er bot_a, og 1, hvis du er bot_b. Deltager 0 er sort (1) i legs[0] og hvid (2) i legs[1]; for deltager 1 er det omvendt. Det er din tur, når leg.status er active, og leg.turn er din farve. Det kan være din tur i begge partier på én gang.

Har du intet lovligt træk, skal du selv sende move -1 (pas); serveren melder ikke pas for dig. I partier mod et menneske håndterer serveren pas som i almindelige spillerum.

På din tur er resterende tid = clocks_ms[din farve - 1] - (server_now_ms - turn_started_ms). clocks_ms er i farveorden (sort, hvid); totals og winner er i deltagerorden (winner 0 eller 1, null ved remis).

Feltnumre

Feltnummer = række × 8 + kolonne, så a1=0, h1=7, a2=8 og h8=63. For eksempel er 19 d3 og 37 f5. board-arrayet bruger samme rækkefølge med 0=tomt, 1=sort, 2=hvid.

    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

På 10×10 (grand, octagon) er felt = række × 10 + kolonne. Kolonnerne er a til j, og den tiende række skrives som 10 eller 0 i koordinater. a1=0, j1=9, a2=10, j10=99 (samme som j0). Samme koordinat har et forskelligt nummer på hver brætstørrelse: d3 er 19 på 8×8 og 23 på 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 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 ## ##

Motoradapter

FlipSight-botforbinderen (Python 3.9+, kun standardbiblioteket) kører på Windows, macOS og Linux og tilslutter en motor på to måder. --engine starter motoren én gang pr. parti, sender én JSON-linje for hvert træk og læser én linje {"move": felt}. En motor, der svarer én linje og afslutter, virker stadig, fordi den startes igen ved næste træk, men en motor, der læser input til ende (sys.stdin.read() osv.), svarer aldrig, så læs én linje ad gangen. legal_moves i forespørgslen viser de lovlige felter; er listen tom, svar -1. --nboard holder en NBoard-motor kørende, én pr. parti; søgedybden sættes med --nboard-depth.

Input-JSON (forbindelsesprogram → adapter)

Indstillinger for forbindelsesprogrammet

API-handlinger

Svareksemplerne viser formatet. Kopiknappen kopierer kun anmodningen og kalder ikke API'et.

POST agent_environment

Rapportér miljø

Rapporterer CPU, OS, motornavn, tråde og øvelsestilstand (practice) for forbindelses-pc'en. Send det ved start, og når værdierne ændres. Svaret indeholder din bot.

ParametreTypePåkrævetBeskrivelse
actionstring "agent_environment"PåkrævetNavnet på den handling, der kaldes
environmentobjectPåkrævetCPU, OS og motornavn for forbindelses-pc'en (op til 120 tegn hver, valgfrit) samt practice (true eller false, valgfrit). practice true betyder, at botten øver sig: Den holdes ude af automatiske kampe, og botkampe, der anmodes om eller accepteres i den tid, er ikke ratede. Forbindelsesprogrammet sender den selv, når det startes med øvelsesmotoren. Serveren husker den sidste værdi, så send den uden practice eller med false, når øvelsen er slut. hash_mb (MB): Pr. motor. Indtast manuelt, hvis forbinderen ikke angiver værdien. ponder (true / false / null): Kun visning. Vælg manuelt, hvis værdien ikke rapporteres. Ret den faktiske indstilling i motoren.

Eksempel på anmodning

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

Eksempel på svar

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

Udfordr

Angiv target_id (bot-ID) eller target_name (botnavn), som vises på botsiden. Indbyggede FlipSight-bots (is_builtin: true) kan udfordres via API’et i alle spiltyper, og serveren starter kampen med det samme. Er der allerede 2 variantkampe mod indbyggede bots, får du HTTP 409 med site bot variant matches are full. Hvis målbotten har slået "Botudfordringer" fra i botstyringen, får du HTTP 409 med bot does not accept bot challenges. Automatiske botpartier følger uanset dette indstillingen for automatisk parring.

Du kan udfordre samme bot tre gange i træk. Vent fem minutter efter den tredje kamp.

Udfordr fra botsiden

ParametreTypePåkrævetBeskrivelse
actionstring "agent_challenge"PåkrævetNavnet på den handling, der kaldes
target_idinteger ≥ 1ValgfritID på den bot, der udfordres
target_namestringValgfritNavn på den bot, der udfordres (i stedet for target_id)
game_modestring std | anti | octagon | grand | reversiValgfritSpil for et botpar. Standard er std. Begge bots skal understøtte det. Standard / Anti / Octagon / Grand (10x10) / Klassisk reversi

Eksempel på anmodning

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

Eksempel på svar

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

POST agent_accept

Accepter

ParametreTypePåkrævetBeskrivelse
actionstring "agent_accept"PåkrævetNavnet på den handling, der kaldes
match_idinteger ≥ 1PåkrævetKamp-ID (negativt for partier mod et menneske)

Eksempel på anmodning

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

Eksempel på svar

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

POST agent_reject

Afvis

ParametreTypePåkrævetBeskrivelse
actionstring "agent_reject"PåkrævetNavnet på den handling, der kaldes
match_idinteger ≥ 1PåkrævetKamp-ID (negativt for partier mod et menneske)

Eksempel på anmodning

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

Eksempel på svar

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

POST agent_move

Send træk

ParametreTypePåkrævetBeskrivelse
actionstring "agent_move"PåkrævetNavnet på den handling, der kaldes
match_idinteger ≠ 0PåkrævetKamp-ID (negativt for partier mod et menneske)
round_nointeger ≥ 0Påkrævet mod en personKun partier mod et menneske: round_no fra kampobjektet
room_created_atstringPåkrævet mod en personKun partier mod et menneske: room_created_at fra kampobjektet
leginteger 0 | 1PåkrævetParti 0 eller 1 (0 for partier mod et menneske)
revisioninteger ≥ 0Påkrævetrevision for det parti, trækket blev beregnet til; 409 stale_revision, hvis partiet er ændret
moveinteger -1..99 | stringPåkrævetFelt 0-(board_size²−1), -1 for pas / d3 / D3 / pass
evalnumber -100..100ValgfritDin motors vurdering efter dette træk, i brikker set fra din side (+ betyder, at du fører, med 2 decimaler). Den går op til antallet af spillelige felter: -64 til 64 på 8x8, -100 til 100 på 10x10 og -88 til 88 på ottekant. Udelader du den eller sender en ugyldig værdi, droppes kun vurderingen, og trækket godtages. Kun kampe mellem bots gemmer den, alle ser den under partiet, også modstanderens bot, og partier mod mennesker ignorerer den.

Eksempel på anmodning

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

Mennesker mod registrerede bots

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

Eksempel på svar

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

POST agent_games

Hent spilprotokoller

Returnerer din bots afsluttede spil som spilprotokoller. Svaret er NDJSON (Content-Type application/x-ndjson) med ét spil på hver linje. Kampe mellem bots og partier mod mennesker er med, men ikke træningspartier eller partier mod sidens egen konto othelloclub. Spil med teknisk annullering er med som result void.

Denne forespørgsel viser ikke din bot som online og tæller ikke med i kontrollen af API-specifikation v2. Hver bot må kalde den én gang per 5 sekunder; et hurtigere kald får 429 med retry_after_sec. Send Accept-Encoding: gzip for at få et komprimeret svar.

ParametreTypePåkrævetBeskrivelse
actionstring "agent_games"PåkrævetNavnet på den handling, der kaldes
sinceinteger ≥ 0ValgfritTidligste updated_ms, der tages med, i ms. Standard 0.
untilinteger ≥ 0ValgfritSeneste updated_ms, der tages med, i ms. Standard: nu.
maxinteger 1..300ValgfritMaksimalt antal spil per svar, 1 til 300. Standard 100.
gamesarrayValgfritSpil, der tages med (std, anti, octagon, grand, reversi). Standard: alle.
orderstring asc | descValgfritasc: ældste først (standard). desc: nyeste først.

Eksempel på anmodning

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

Eksempel på svar

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

Spilprotokoller

En spilprotokol (record) er ét JSON-objekt for ét afsluttet spil. Den indeholder spillere, resultat, ratings, åbning og tidspunktet for hvert træk, set fra din bots side. Du får det samme objekt to steder.

  1. Hændelse for afsluttet spil: Når et spil slutter, har den sidste match-hændelse (status finished eller aborted) record med.
  2. agent_games: Returnerer afsluttede spil, ét per linje. Brug det til tidligere spil og spil, du har misset.

Træk bruger sidens partinotation. Hvert træk er to tegn, og pas er pa. Kolonnerne går fra a til j og rækkerne fra 1 til 9; på 10×10 er den tiende række 0 (j0 er felt 99). squares giver de samme træk som feltnumre (-1 for pas), og colors giver den side, der trak, B eller W.

Spil, der slutter, mens din strøm er nede, og partier mod mennesker, hvis spilprotokol endnu ikke er klar, har ingen record i hændelsen for afsluttet spil. Udfyld sådanne huller med agent_games på denne måde.

  1. Startpunkt: Send updated_ms fra din nyeste gemte spilprotokol som since. since medtager selve tidspunktet, så din sidste spilprotokol kommer igen.
  2. Spring dubletter over: Spring en spilprotokol over, når du allerede har dens kind og id.
  3. Næste side: Kald igen med det nyeste updated_ms, du har modtaget. Stop, når et svar ikke bringer nye spilprotokoller.
  4. Ændrede spilprotokoller: Et spil, der ændres efter sin afslutning, for eksempel ved en teknisk annullering, kommer igen med et nyere updated_ms. Erstat den gamle spilprotokol med den nye.

agent_games

Felter i spilprotokollen
FeltTypeBeskrivelse
formatintegerVersionsnummer for spilprotokollens format, nu 1. Nye felter kan blive tilføjet i version 1; nummeret stiger kun, når et eksisterende felt skifter betydning.
kindstringbot: en kamp mellem bots med to partier. human: et enkelt parti mod et menneske.
idintegerKamp-ID for kind bot, parti-ID for kind human. kind og id tilsammen identificerer en spilprotokol.
urlstringSide til at genafspille spillet
room_id, round_nointeger | nullKun partier mod et menneske: rum og runde
game_modestringSpil (std, anti, grand, octagon, reversi)
opening_modestringrandom12: den tilfældige start med 12 brikker i en kamp mellem bots. xot eller std: hvordan et parti mod et menneske startede.
board_sizeinteger 8 | 10Felter pr. side, 8 eller 10
time_limit_secintegerSekunder pr. parti, pr. farve
autobooleanOprettet af automatisk matching
rankedbooleanOm kampen er ratet
rating_appliedbooleanOm resultatet ændrede ratings
statusstringfinished, eller aborted ved teknisk annullering
finish_reasonstring | nullHvorfor spillet sluttede: de samme værdier som state.finish_reason for kampe mellem bots, spillerummets værdi for partier mod et menneske.
resultstringwin, loss, draw eller void, set fra din bots side
started_ms, finished_ms, updated_msinteger | nullStart- og sluttidspunkt i ms; started_ms er null for partier mod et menneske. updated_ms er, hvornår spilprotokollen sidst blev ændret, normalt sluttidspunktet, og since og until sammenlignes med det.
meobjectDin bot: bot_id, name, engine, rating_before, rating_after. engine er motornavnet, der blev rapporteret ved start; begge ratings er null, når spillet ikke var ratet.
opponentobjectModstander: kind (bot, human eller guest), name, engine, rating_before, rating_after. En bot har også bot_id og builtin, et menneske player_id.
discs[integer, integer]Score for din bot og modstanderen: summen af begge partier (state.totals) for kampe mellem bots, antal brikker for partier mod et menneske.
opening, opening_squares, opening_colorsstring, integer[], stringÅbningstræk før partierne i samme notation: den tilfældige start med 12 brikker eller XOT-åbningen.
legs[].my_colorstringDin bots farve i dette parti, B eller W
legs[].statusstringactive, finished, timeout, stopped
legs[].discs[integer, integer]Antal brikker i farveorden (sort, hvid)
legs[].result_discs[integer, integer] (optional)Valgfri tildelt score [sort, hvid] for et parti tabt på tid; læg den sammen i stedet for brikkerne. Score for den side, der løb tør for tid, og for modstanderen: std og reversi 0 til 64, grand 0 til 100, octagon 0 til 88, anti 64 til 0. Det andet parti fortsætter, og summerne afgør vinderen, når begge partier er slut. Ældre afsluttede registreringer genberegnes ikke.
legs[].moves, squares, colorsstring, integer[], stringPartiets træk efter åbningen: moves som streng, squares som tal, colors som B eller W for hvert træk.
legs[].at_ms, used_ms, left_ms(integer | null)[]For hvert træk: hvornår det blev spillet i ms, den brugte tid og den trækkende sides resterende tid bagefter. Spilletidspunkter er null i partier mod mennesker, og ukendte værdier er også null.
legs[].evals(number | null)[] (optional)Den vurdering, den trækkende side sendte med sit træk, i brikker set fra dens side. Træk sendt uden vurdering har null. Feltet mangler, når intet træk i partiet havde en.

Fejl

Fejl ser sådan ud: {"ok": false, "error": "…"}. Ved 401: stop og kontrollér tokenet. Ved 409: kontrollér tur, revision og lovlige træk i din seneste status (forbind strømmen igen, hvis du er i tvivl). 410 betyder, at handlingen er fjernet (agent_poll fra 2026-11-22 00:00 (UTC+9)): brug hændelsesstrømmen. 429 betyder for mange forespørgsler (over 20 i sekundet fra én bot eller 40 i sekundet fra alle bots på samme IP-adresse til bot_match_api.php). Ved 429, 5xx og forbindelsesfejl: send samme forespørgsel igen efter 0,2 til 0,5 s (følg Retry-After, hvis den findes), og forlæng ventetiden efter nogle forsøg. Send aldrig et ulovligt træk igen.

{"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
Hent status (fjernet 2026-11-22)

Fjernet 2026-11-22 00:00 (UTC+9): derefter returnerer det HTTP 410 {"ok": false, "error": "agent_poll was removed; use bot-stream"}. Få din tilstand fra hændelsesstrømmen, og forbind den igen for at synkronisere. Indtil da svarer det stadig, men fra 2026-11-21 23:40 (UTC+9) udelades en registreret bot, der har kaldt det inden for de seneste 10 minutter, fra automatisk matching.

Implementer API'et selv
Copyright © Othelloclubthe.othelloclub.com@gmail.com All rights reserved.