API-dokumentaatio

Vaiheittainen opas aloittelijoille

Mitä tarvitset

  • FlipSight-tili.
  • Yksi botin kuva: GIF-, JPG- tai PNG-tiedosto, enintään 5 Mt, leveys ja korkeus vähintään 175 px.
  • Oma tietokone botin käyttämiseen Bottisi siirrot lasketaan tietokoneella, jossa yhdistin on käynnissä. Samallakin moottorilla vahvuus voi vaihdella tietokoneen tehon ja moottorin asetusten mukaan, ja jos vaihdat tietokonetta tai asetuksia, vahvuusluku voi muuttua sen mukaisesti.
  • Python 3, ilmainen ohjelma, joka suorittaa yhteysohjelman. Versio 3.9 tai uudempi toimii; 3.11 tai uudempi on suositeltava. Tarkistat sen vaiheessa 5.
  • Oma bottimoottori. Yhteysohjelman mukana tulee harjoitusmoottori testaamista varten.

1. Rekisteröi bottisi

Kirjaudu sisään ja avaa bottisivu (othelloclub.com/fi/flipsight/lab). Kirjoita yläosan ruudussa Rekisteröi bottini nimi kenttään Botin nimi (2–24 merkkiä). Jätä kohdassa Tuetut pelit toistaiseksi valituksi vain Standard. Valitse kuva kohdassa Lataa botin kuva ja paina sitten painiketta Rekisteröi bottini.

Onnistuminen näyttää tältä: näkyviin tulee ruutu Yhteystunniste (näytetään vain kerran), jossa on pitkä teksti, joka alkaa merkeillä fsbm_.

2. Ota tunniste talteen

Tämä pitkä teksti on tunniste, vain bottiasi varten oleva salasana. Yhteysohjelma todistaa sillä palvelimelle, että se toimii tämän botin puolesta. Kopioi se kokonaan ja liitä se väliaikaisesti jonnekin, esimerkiksi tekstieditoriin. Kun suljet ruudun, et näe samaa tunnistetta enää uudelleen.

Käsittele tunnistetta kuin salasanaa. Älä näytä sitä kenellekään äläkä julkaise siitä kuvakaappausta. Jos kadotat sen tai joku näkee sen, avaa bottiluettelossa Hallitse ja paina Luo yhteystunniste. Kun saat uuden tunnisteen, vanha lakkaa toimimasta heti.

3. Lataa yhteysohjelma

Lataa ZIP-tiedosto painamalla Lataa Python-esimerkit ja pura se. Tässä oppaassa purettua kansiota kutsutaan nimellä ”bottikansio”. Sijoita se paikkaan, josta löydät sen helposti, esimerkiksi työpöydälle.

Onnistuminen näyttää tältä: bottikansiossa on README.md-tiedosto ja tools-kansio.

4. Avaa pääte bottikansiossa

Pääte on ikkuna, johon kirjoitetaan komentoja. Avaa se järjestelmäsi mukaan seuraavasti.

macOS: paina Command+Space, kirjoita Terminal ja avaa se. Kirjoita cd ja yksi välilyönti, vedä bottikansio ikkunaan ja paina sitten Enter.

Linux: napsauta tiedostonhallinnassa bottikansiota hiiren oikealla painikkeella ja valitse Avaa päätteessä. Valikon nimi voi vaihdella jakeluittain. Jos tällaista valikkoa ei ole, avaa pääte ja käytä komentoa cd kuten macOSissa.

Windows: avaa bottikansio Resurssienhallinnassa. Kirjoita yläreunan osoiteriville powershell ja paina Enter. Kansioon avautuu PowerShell-ikkuna.

Tarkistus: kirjoita alla oleva komento ja paina Enter. Onnistuminen tarkoittaa, että luettelossa näkyvät README.md ja tools. Komento on sama macOSissa, Linuxissa ja Windowsin PowerShellissä.

ls

5. Tarkista Python

Kopioi samassa ikkunassa järjestelmääsi vastaava komento, liitä se ja paina Enter. Voit käyttää kunkin koodiruudun oikeassa yläkulmassa olevaa kopiointipainiketta.

macOS / Linux

python3 --version

Windows PowerShell

py --version

Onnistuminen näyttää tältä: 3:lla alkava versio, esimerkiksi Python 3.11.9. Versio 3.9 tai uudempi toimii. Jos komentoa ei löydy, asenna Python alla olevien ohjeiden mukaan, sulje ikkuna ja aloita uudelleen vaiheesta 4.

macOS: lataa python.org-sivustolta macOS-asennusohjelma (.pkg) ja asenna se. Suorita sitten kerran Install Certificates.command Ohjelmat-kansion Python-kansiosta. Se valmistelee suojattuihin (HTTPS) yhteyksiin tarvittavat varmenteet.

Linux: asenna python3 jakelusi ohjelmistokeskuksella tai paketinhallinnalla.

Windows: asenna Python install manager python.org-sivustolta.

python.org

6. Syötä tunniste

Tallenna tunniste ympäristömuuttujaan. Se on väliaikainen asetus, joka on olemassa vain tässä pääteikkunassa. Sen nimi on FS_BOT_TOKEN. Kopioi alta järjestelmääsi vastaava yksirivinen komento, liitä se ja paina Enter kerran. Näkyviin tulee Bot token, ja se odottaa syötettäsi. Liitä nyt vaiheessa 2 kopioimasi tunniste ja paina 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

macOSissa ja Linuxissa liitettyä tunnistetta ei näytetä, ja Windowsissa näet merkkien tilalla *. Molemmat ovat normaaleja. Koska tunnistetta ei kirjoiteta komentoon, se ei jää komentohistoriaan. Asetus on voimassa vain tässä ikkunassa. Jos suljit sen tai avasit uuden ikkunan, toista vaiheet 4 ja 6.

Liitä tunnus PowerShelliin näppäimillä Ctrl+V.

Onnistuminen näyttää tältä: seuraavan komennon kehote palaa ilman virhettä.

7. Käynnistä yhteysohjelma

Kopioi samassa ikkunassa alla oleva komento sellaisenaan, liitä se ja paina Enter. Älä muuta sen tiedostonimiä. Bottisi yhdistyy harjoitusmoottorilla. Se on hyvin heikko moottori, joka pelaa sen laillisen ruudun, jolla on pienin numero.

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'

On normaalia, ettei komento tulosta tekstiä eikä palaa komentokehotteeseen ollessaan käynnissä. Pidä tämä ikkuna auki, yhteysohjelma ja pelimoottori käynnissä sekä estä tietokonetta siirtymästä lepotilaan, jotta botti pysyy verkossa. Ikkunan sulkeminen tai Ctrl+C lopettaa molemmat ohjelmat ja katkaisee botin yhteyden. Suorita yllä oleva komento uudelleen yhdistääksesi botin. Yhteysohjelma hyväksyy muiden bottien haasteet automaattisesti.

Niin kauan kuin botti toimii harjoitusmoottorilla, se ei saa automaattisia otteluita, eivätkä sen ottelut muita botteja vastaan, edes itse pyydetyt, vaikuta vahvuuslukuun. Käynnistä se uudelleen omalla moottorillasi (vaihe 10), niin siitä lähtien se saa pareja ja ottelut vaikuttavat vahvuuslukuun.

Onnistuminen näyttää tältä: bottisivun luettelossa Rekisteröidyt botit bottisi nimen oikealla puolella oleva pallo on vihreä. Kun viet osoittimen sen päälle, näkyy Paikalla.

8. Testaa ensimmäisellä ottelulla

Valitse bottisivulla bottisi kohdassa Pelaava bottini. Valitse mikä tahansa botti luettelosta FlipSight-botit, paina Haasta ja vahvista avautuvassa ikkunassa. Kaikissa pelityypeissä palvelin laskee FlipSight-bottien siirrot, joten pelihuonetta ei tarvitse pitää auki.

Onnistuminen näyttää tältä: pelihuoneessa näkyy kaksi lautaa, ja bottisi asettaa nappulan jokaisella vuorollaan. Harjoitusmoottori on hyvin heikko, joten häviäminen on normaalia.

9. Pidä käynnissä ikkunan sulkemisen jälkeen (valinnainen)

Pysäytä yhteysohjelma ensimmäisen pelin jälkeen vaiheen 7 ikkunassa painamalla Ctrl+C. Käynnistä se samassa ikkunassa alla olevalla komennolla. Pidä tietokone hereillä.

macOS / Linux

Käytä screen-ohjelmaa. Korvaa mybot kullekin botille omalla nimellä. Paina käynnistyksen jälkeen Ctrl+A ja sitten D, niin voit sulkea ikkunan. Pysäytä botti palaamalla istuntoon alemmalla komennolla ja painamalla Ctrl+C.

Käynnistys

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

Pysäytys

screen -r mybot

Windows PowerShell

Windows: tehtäväpalkkiin ilmestyy pienennetty ikkuna, jossa botti toimii. Voit sulkea nykyisen PowerShell-ikkunan. Pysäytä botti avaamalla pienennetty ikkuna ja painamalla Ctrl+C tai sulkemalla kyseinen ikkuna.

Käynnistys

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. Vaihda omaan moottoriisi

Yhteystestin jälkeen vaihda omaan moottoriisi: Edaxille ja Egaroucidille alla olevat omat valitsimet, muille yhteensopiville --nboard ja itse tehdylle moottorille JSON. Tunniste pysyy samana.

Valitse kohdassa Tuetut pelit pelimuunnelma (Anti, 10x10, Octagon, klassinen Reversi) vain, jos moottorisi tuntee sen säännöt. Muut botit ja ihmiset voivat haastaa bottisi kaikissa valituissa peleissä. Muuta valintaa avaamalla bottiluettelossa Hallitse, muokkaamalla kohtaa Tuetut pelit ja painamalla Tallenna. Et voi muuttaa sitä, kun ottelu on käynnissä tai haaste odottaa.

Yleisiä ongelmia

OireSyy ja korjaus
Botilla on harmaa pallo (poissa).Tarkista, että yhteysohjelman ikkuna on yhä käynnissä. Se pysähtyy, kun suljet ikkunan, painat Ctrl+C tai tietokone menee lepotilaan.
Ilmoitus kertoo, että komentoa ei löytynyt.
command not found / is not recognized
Python puuttuu, tai ikkunaa ei avattu uudelleen asennuksen jälkeen. Katso vaihe 5, avaa uusi ikkuna ja aloita uudelleen vaiheesta 4.
Ilmoitus kertoo, että tiedostoa ei voi avata.
can't open file
Suoritit komennon bottikansion ulkopuolella. Siirry bottikansioon kuten vaiheessa 4 ja tarkista komennolla ls, että README.md ja tools näkyvät luettelossa.
Ilmoitus kertoo, että tunniste puuttuu, ja ohjelma sulkeutuu.
FS_BOT_TOKEN is missing or invalid
Tässä ikkunassa ei ole tunnistetta. Jos avasit uuden ikkunan, toista vaihe 6.
Ilmoitus kertoo, että tunniste hylättiin, ja ohjelma pysähtyy.
Bot credential rejected
Tunniste liitettiin väärin, tai se on vanha. Kun luot uuden tunnisteen tai poistat botin käytöstä, vanha tunniste ei enää toimi. Aloita uudelleen vaiheesta 6 uusimmalla tunnisteella.
Sama virherivi toistuu jatkuvasti.
Connection/state error
Tarkista internetyhteys. Tarkista macOSissa, että suoritit vaiheen 5 tiedoston Install Certificates.command. Jos virhe näkyy vain otteluiden aikana, palvelin saattaa hylätä moottorisi siirron laittomana. Yhteysohjelma lähettää saman siirron uudelleen, joten moottori on korjattava.
Haastepainike ei toimi, tai haastetta ei hyväksytä.Valitse Pelaava bottini ja tarkista, että molemmat botit ovat verkossa. Vastustajan on hyväksyttävä suorat haasteet, ja sillä on oltava vapaa pelipaikka. Haaste vanhenee 120 sekunnissa, jos siihen ei vastata.
Botti ei tee siirtoa ja häviää sitten ajan loppumiseen, tai ottelu mitätöidään.
Engine failed for match
Moottori ei vastannut ajoissa, tai sen vastaus oli väärässä muodossa. Tarkista moottorin komento ja sen yhden rivin JSON-tuloste. Jos botti ei tee ensimmäistä siirtoaan 30 sekunnin kuluessa alusta, ottelu mitätöidään.
Pelimuunnelmien haasteita ei tule.Haasteikkunassa näkyvät vain pelit, joita molemmat botit tukevat. Tarkista, että peli on valittu bottisi kohdassa Tuetut pelit ja että myös toinen botti tukee sitä. Valinnalla --edax tai --nboard yhdistetyllä botilla pitäisi olla valittuna vain Standard.

Sanasto

TermiMerkitys
APISovittu tapa, jolla ohjelmat lähettävät pyyntöjä ja vastauksia. Yhteysohjelma hoitaa sen puolestasi.
TunnisteVain bottiasi varten oleva salasana. Yhteysohjelma todistaa sillä palvelimelle, mikä botti se on.
PääteIkkuna, johon kirjoitetaan komentoja. Windowsissa käytä PowerShelliä.
YmpäristömuuttujaVäliaikainen asetus, joka välitetään yhdestä pääteikkunasta käynnistetyille ohjelmille. Se katoaa, kun ikkuna suljetaan.
JSONMuoto tietojen kirjoittamiseen tekstinä. Esimerkki: {"move":19}
MoottoriOhjelma, joka tarkastelee asemaa ja valitsee siirron.
SovitinPieni ohjelma, joka muuntaa tietoja moottorisi ja yhteysohjelman välillä.
NBoardAvoin muoto, jolla Othello-moottorit ja lautaohjelmat vaihtavat asemia ja siirtoja. Sitä tukevat moottorit, kuten NTest, yhdistetään ilman sovitinta.
Laillinen siirtoRuutu, johon saat pelata nyt. Palvelin luettelee ne kentässä legal_moves.

Oman moottorin yhdistäminen

Käytä enintään 4 säiettä moottoria kohden. Botin ottelussa pelataan kaksi peliä samanaikaisesti, joten säikeitä on yhteensä enintään 8.

Edax: --edax

Alla olevissa asennus- ja käynnistysesimerkeissä käytetään Edax 4.6:ta ja Egaroucid for Console 7.8.2:ta.

Edax 4.6 ei sisälly yhteysohjelmaan. Lataa käyttöjärjestelmäsi tiedosto kohdan Edax 4.6 Assets-osiosta, siirrä se bottikansioon ja pura se alla olevilla valmistelukomennoilla. Windows- ja Linux-komennot ovat x86-64-tietokoneille.

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

Valmistelu (vain ensimmäisellä kerralla)

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

Käynnistys

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

Valmistelu (vain ensimmäisellä kerralla)

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

Käynnistys

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:sta ei ole virallista macOS-ohjelmatiedostoa. Lataa saman julkaisun Source code (tar.gz) ja edax-4.6-linux-x86.tar.gz. Käännä Mac-ohjelma lähdekoodista ja poimi Linux-arkistosta vain yhteinen arviointitiedosto data/eval.dat. Xcode Command Line Tools tarvitaan. Valmistelukomennot kääntävät lähdekoodin.

Valmistelu (vain ensimmäisellä kerralla)

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)

Käynnistys

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

Edax voidaan yhdistää myös pelkällä ohjelmapolulla käyttäen alla olevaa --edax-valintaa. Erillistä sovitinta ei tarvita. Yhdistämisohjelma käynnistää Edaxin xboard-tilassa ja lähettää molempien jäljellä olevat ajat ennen jokaista siirtoa; Edax päättää miettimisajan itse oman kellonsa perusteella (yhdistämisohjelma v1.4.8 tai uudempi). Pelin aikana Edax säilyttää pelinsä ja hash-taulunsa, ja valinnalla --engine-ponder on se hakee myös vastustajan ajalla. --edax-protocol nboard käyttää aiempaa NBoard-yhteyttä.

Korvaa komennon polku oman ohjelmasi täydellä polulla. Laita välilyöntejä sisältävät polut lainausmerkkeihin. Jos arviointitiedostoa ei löydy automaattisesti, määritä eval.dat valitsimella --edax-eval.

Valinnoilla --edax ja --nboard tehty yhteys pelaa vain tavallisia 8×8-pelejä. Jätä tämän botin kohtaan Tuetut pelit valituksi vain Standard. Jos saapuu pelimuunnelma, yhteysohjelma ei kysy moottorilta, siirtoa ei pelata, ja peli mitätöidään tai hävitään ajan loppumiseen.

Egaroucid: --egaroucid

Valmistele Egaroucid for Console. Valitse konsoliohjelma ja säilytä resources-kansio paikallaan. macOS- ja Linux-järjestelmissä käytetään virallisten ohjeiden mukaan käännettyä ohjelmaa. Asema ja jäljellä oleva aika välitetään komennoilla setboard, settime ja go ilman sovitinta.

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"

Molemmat tilat tukevat vain tavallista 8×8-peliä, yksi moottori kutakin samanaikaista peliä kohti. --max-think-seconds on siirron turvaraja (oletus 10 sekuntia). Jos Egaroucid saavuttaa rajan, haku lopetetaan, tehdään laillinen varasiirto ja moottori käynnistetään seuraavalla vuorolla uudelleen.

NBoard-moottorit, kuten NTest: --nboard

NBoard on graafinen Othello-ohjelma, jota voi käyttää NTestin kanssa. NBoard-protokolla on sen julkinen viestintämuoto pelimoottoreille; sitä tukevat moottorit, kuten NTest, yhdistetään valinnalla --nboard. Jokaista peliä varten pidetään käynnissä yksi moottori. Myös Edax tukee sitä, mutta yhdistä Edax yllä olevalla valinnalla --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"

Valinnoilla --edax ja --nboard tehty yhteys pelaa vain tavallisia 8×8-pelejä. Jätä tämän botin kohtaan Tuetut pelit valituksi vain Standard. Jos saapuu pelimuunnelma, yhteysohjelma ei kysy moottorilta, siirtoa ei pelata, ja peli mitätöidään tai hävitään ajan loppumiseen.

Itse tehty moottori: yhdistä JSONin kautta

Lue tämä osa vain, jos haluat liittää itse kirjoittamasi moottorin. Jos käytössäsi on Edax, Egaroucid tai jokin NBoard-moottori, olet jo valmis yllä olevien ohjeiden jälkeen ja voit ohittaa tämän osan.

Aina kun on bottisi vuoro, yhteysohjelma suorittaa tiedoston my_adapter.py kerran. Se antaa nykyisen aseman yhtenä rivinä (missä nappulat ovat, kenen vuoro on, mitkä ruudut ovat laillisia, paljonko aikaa on jäljellä), my_adapter.py vastaa yhdellä ruudulla yhtenä rivinä, ja yhteysohjelma pelaa sen siirron palvelimella. my_adapter.py on pieni Python-tiedosto niiden välissä, ja se kysyy siirron moottoriltasi. Yhteysohjelma hoitaa palvelinyhteyden, tunnisteen ja siirtojen lähettämisen, joten tämän tiedoston ei tarvitse koskaan huolehtia niistä.

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

Millainen moottorisi on?

  • Moottori, joka valitsee siirtonsa Python-koodissa: käytä alla olevaa esimerkkiä A.
  • Ohjelmatiedosto, joka tulostaa yhden vastausrivin ja sulkeutuu joka kerta, kun se suoritetaan: käytä alla olevaa esimerkkiä B.
  • Ohjelmatiedosto, joka pysyy auki ja vaihtaa komentoja jatkuvasti: jos se tukee NBoardia, liitä se yllä olevalla --nboard-valinnalla. Muulla protokollalla sovita esimerkki B siihen ja anna my_adapter.py:n pitää moottori auki ja vaihtaa rivi kerrallaan silmukassa.

Vaihe 1: tiedosto, joka vain tarkistaa yhteyden (my_adapter.py)

Luo bottikansioon (jossa README.md ja tools ovat) tiedosto nimeltä my_adapter.py, liitä alla oleva koodi siihen sellaisenaan ja tallenna. Tämä tiedosto ei käytä mitään moottoria, vaan vastaa yksinkertaisesti ensimmäisellä laillisella ruudulla. Sen avulla varmistat, että yhteys toimii, ennen kuin liität oman moottorisi.

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)

Tarkista syöte ja tuloste ennen yhdistämistä

Laatikon 1 komento syöttää esimerkkiaseman suoraan sovittimelle. Sen pitäisi tulostaa yksi rivi: {"move": 19}. Kun näet tämän rivin, laatikon 2 komento käynnistää yhteysohjelman tällä sovittimella siinä ikkunassa, jossa on vaiheen 6 tunniste. Suorita kaksi laatikkoa erikseen. Jos moottorisi lukee tätä JSON-muotoa itse, voit kirjoittaa sen komennon suoraan valitsimen --engine perään.

1. Testaa pelkkä sovitin

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. Käynnistä yhteysohjelma sovittimen kanssa

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'

Vaihe 2: vaihda tiedostoon, joka kutsuu moottoriasi

Kun vaihe 1 toimii, korvaa tiedoston my_adapter.py koko sisältö alla olevalla esimerkillä A tai B. Muuta vain EDIT-merkityt rivit ja jätä muu ennalleen. Suorita sitten yllä oleva testikomento 1 uudelleen ja tarkista, että näkyviin tulee yksi vastausrivi. Siirron valitsi nyt moottorisi, joten on normaalia, että ruutu on jokin muu kuin 19.

Esimerkki A: moottori, joka valitsee siirtonsa Python-funktiolla

Tässä esimerkissä oletetaan, että on tiedosto nimeltä my_engine.py ja siinä funktio search, joka valitsee siirron. Muuta kohdassa EDIT 1 tiedoston ja funktion nimi ja kohdassa EDIT 2 funktiolle annettavat arvot omaan moottoriisi sopiviksi. Funktion pitää palauttaa ruudun numero (0:sta 63:een) tai koordinaatti, kuten 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)
Esimerkki B: moottori, joka on ohjelmatiedosto

Tässä esimerkissä oletetaan, että ohjelma lukee yhden rivin, jossa on 64 lautamerkkiä, siirtovuorossa oleva puoli ja miettimisaika millisekunteina, ja vastaa yhdellä koordinaattirivillä, kuten D3 (. = tyhjä, X = musta, O = valkoinen). Jokaisella moottorilla on oma muotonsa, joten muuta kohdassa EDIT 1 ohjelmatiedoston nimi, kohdassa EDIT 2 moottorille lähetettävä rivi ja kohdassa EDIT 3 vastauksen lukeva osa omaan moottoriisi sopiviksi.

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)

Miettimisaika: bottipeleissä kummallakin botilla on 1 minuutti peliä kohden, joten pitkä miettiminen yhden siirron kohdalla johtaa nopeasti häviöön ajan loppumiseen. Esimerkkien think_ms jakaa jäljellä olevan ajan (remaining_ms) jäljellä olevien siirtojesi määrällä ja päättää näin tämän siirron ajan. budget_ms ei ole aika, joka tähän siirtoon pitäisi käyttää. Se on pisin aika, jonka yhteysohjelma odottaa vastausta (oletuksena 10 sekuntia). Jos vastaus tulee sitä myöhemmin, botti ei voi jatkaa kyseistä peliä ja häviää sen ajan loppumiseen. Anna siis moottorillesi think_ms eikä budget_ms.

Kun jokin menee vikaan: jos moottorin kutsu epäonnistuu, esimerkkitiedostot kirjoittavat syyn tiedostoon my_adapter.log ja pelaavat sen sijaan ensimmäisen laillisen ruudun. Jos siirrot näyttävät oudoilta, avaa ensin tuo tiedosto. Yhteysohjelma ei näytä sovittimen virheilmoituksia näytöllä. Käytä print-komentoa vain yhteen vastausriviin ja kirjoita kaikki virheenjäljitysteksti tiedostoon.

Nopeus: yhteysohjelma pitää my_adapter.py:n käynnissä jokaista peliä varten ja lähettää rivin siirtoa kohden. Tiedosto, joka vastaa yhden rivin ja sulkeutuu kuten esimerkit, käynnistetään uudelleen seuraavalla siirrolla, joten moottorisikin käynnistyy joka kerta uudelleen. Jos moottori käynnistyy hitaasti tai sen pitää säilyttää aiempien siirtojen työ, tee my_adapter.py:stä silmukka: lue rivi, vastaa rivi, toista. Älä lue syötettä loppuun asti, ja tee flush jokaisen vastauksen jälkeen.

Tämän osan loppu on viiteaineistoa siitä, mitä yhteysohjelma ja my_adapter.py vaihtavat keskenään. Jos käytät yllä olevia esimerkkitiedostoja sellaisenaan, sinun ei tarvitse lukea sitä.

Syöte-JSON (yhteysohjelma → sovitin)

Tämä on yhteysohjelman lähettämää esimerkkidataa, ei suoritettavaa koodia. Älä tallenna sitä Python-tiedostoksi. Pelin aikana ajantasaiset tiedot lähetetään automaattisesti joka vuorolla.

Alla on esimerkki tavallisen 8×8-laudan alkuasemasta. Oikeissa peleissä yhteysohjelma täyttää nykyisen aseman. board luettelee ruudut a1:stä oikealle ja sitten seuraavan rivin; 0=tyhjä, 1=musta, 2=valkoinen. color=1 pyytää mustan siirtoa. legal_moves luettelee ruudut, joihin saat pelata. remaining_ms on pelikellon jäljellä oleva aika ja budget_ms pisin aika, jonka yhteysohjelma odottaa tämän siirron vastausta, molemmat millisekunteina (1000 = 1 sekunti). Pelimuunnelmien kentät ja esimerkit ovat alempana muunnelmia käsittelevässä osiossa.

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

Vastaus-JSON (sovitin → yhteysohjelma)

Kirjoita yksi alla olevista vastauksista yhtenä JSON-rivinä, joka päättyy rivinvaihtoon. move on ruudun numero tai koordinaatti, eikä isoilla ja pienillä kirjaimilla ole väliä. 8×8-laudalla d3 on (3−1)×8+3 = 19. Valitse aina saamastasi legal_moves-luettelosta. Bottipareissa, kun laillista siirtoa ei ole, lähetä -1 tai pass; ihmistä vastaan pelatuissa peleissä palvelin hoitaa pakolliset passit. Kirjoita stdout-tulosteeseen vain vastausrivi, ei muita viestejä.

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

Valinnainen: lisää vastaukseen environment, niin moottori ilmoittaa todelliset säikeet, hash-koon megatavuina ja ponderin (yhdistämisohjelma v1.4.6 tai uudempi). Yhdistämisohjelma hyväksyy vain sallitun alueen luvut ja arvot true/false ja näyttää ne botin tiedoissa. Kun oma sovittimesi lisää eval-arvon, yhdistämisohjelma lähettää sen siirron mukana bottien välisissä otteluissa (esimerkiksi {"move":19,"eval":1.5}). eval on arviosi siirron jälkeen nappuloina omalta puoleltasi, enintään pelin pelattavien ruutujen määrä; --edax, --egaroucid ja NBoard-moottorit lähettävät sen itse, kun päivität versioon v1.5.3.

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

Moottoripyyntöjen esimerkit peleittäin

Lataukset

Lataa Python-esimerkit

GitHub: flipsight-othello-bot-connector

OpenAPI 3.1 JSON

README.md

.zip sisältää oppaan, yhdistimen ja esimerkkimoottorin; .json on API-määritys ja .md on opas.

API:n toteuttaminen itse

Pysäytä ensin harjoitusbotin yhteysohjelma. Avaa tapahtumavirta vaiheen 6 tunnuksella. Pidä yksi yhteys auki tunnusta kohti. Jokaisella rivillä on yksi JSON-tapahtuma.

Tapahtumavirta

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"

Heti hello-tapahtuman jälkeen saat state-tapahtuman. Esimerkissä näkyvät bottisi numero 2 tarvitsemat kentät.

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

Bottisi pelaa toisella laudalla (leg 1) mustilla (1). Kun turn on 1, valitse siirto legal_moves-listasta ja lähetä mukana laudan revision. Kun lähetät oikean siirron, aseta tunnus toisessa päätteessä kuten vaiheessa 6 ja käytä meneillään olevan pelin arvoja.

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

Tapahtumavirta

API:n toteuttaminen itse

TyyppiKuvaus
helloYhteys avattu. bot_id on bottisi tunniste.
stateKorvaa käynnissä olevien pelien ja kutsujen luettelo. Jos olet bot_b, voit hyväksyä pending-kutsun toiminnolla agent_accept.
matchPäivitä tällä id:llä merkitty peli. Tarkista jokaiselta aktiiviselta laudalta, onko bottisi vuorossa.
pingYhteysmerkki 10 sekunnin välein. Siihen ei tarvitse vastata.
closingViimeinen rivi ennen kuin palvelin sulkee virran. Jos reason on overflow (liikaa lähettämättömiä rivejä) tai server_shutdown, yhdistä uudelleen ja ota tila kiinni state-tapahtumasta. replaced tarkoittaa, että samaa tunnusta käytetään toisessa paikassa. Älä yhdistä heti uudelleen: odota vähintään 30 sekuntia ja pidempään, jos se toistuu. Käytä kutakin tunnusta vain yhdessä paikassa.
Otteluobjekti (matches[])
KenttäTyyppiKuvaus
idintegerOttelun ID (negatiivinen ihmistä vastaan pelatuissa peleissä)
kindstringhuman, kun vastassa on ihminen
bot_aintegerOsallistujan 0 botin ID (ihmiselle 0)
bot_bintegerOsallistujan 1 botin ID (ihmiselle 0)
game_modestringPeli (std, anti, grand, octagon, reversi)
time_limit_secintegerSekunnit peliä ja väriä kohden
statusstringpending, running, finished, aborted, rejected, expired
expires_msintegerHyväksynnän määräaika (millisekunteina)
rankedbooleanLasketaanko ottelu vahvuuslukuun
state.statusstringactive, finished tai aborted
state.game_modestringPeli (std, anti, grand, octagon, reversi)
state.board_sizeinteger 8 | 10Ruutuja sivulla, 8 tai 10
state.blocked_squaresinteger[]Käyttökelvottomat ruudut (vain Octagon, ei järjestetty)
state.legsarrayPelit (bottien kesken 2, ihmistä vastaan 1)
state.totals[integer, integer]Molempien pelien nappulasummat osallistujittain
state.winnerinteger | nullVoittanut osallistuja 0 tai 1, tasapelissä null
state.finish_reasonstring | nulldiscs, timeout, double_timeout, disconnect, no_first_move
Peliobjekti (state.legs[])
KenttäTyyppiKuvaus
boardinteger[64 | 100]64 / 100 ruutua, 0=tyhjä 1=musta 2=valkoinen
turnintegerVuorossa oleva väri, 1 (musta) tai 2 (valkoinen)
legal_movesinteger[]Siirtovuorossa olevan värin lailliset ruudut. Tyhjä päättyneissä peleissä
placed{"1": integer, "2": integer}Asetetut nappulat väreittäin, avaimet "1" (musta) ja "2" (valkoinen)
black_participantintegerOsallistuja, joka pelaa mustalla tässä pelissä
clocks_ms[number, number]Jäljellä olevan ajan perusarvot värijärjestyksessä (musta, valkoinen)
turn_started_msintegerPalvelimen aika nykyisen vuoron alkaessa
revisionintegerKasvaa yhdellä aina, kun tämä peli muuttuu
statusstringactive, finished, timeout, stopped
historyarrayPelatut siirrot (color, participant, move, at_ms, eval)
discs[integer, integer]Nappulamäärät värijärjestyksessä (musta, valkoinen)
result_discs[integer, integer] (optional)Valinnainen määrätty tulos [musta, valkoinen] pelille, joka hävittiin ajan loppumiseen; summaan lasketaan tämä nappuloiden sijaan. Ajan ylittäneen puolen ja sen vastustajan tulokset: std ja reversi 0 ja 64, grand 0 ja 100, octagon 0 ja 88, anti 64 ja 0. Toinen peli jatkuu, ja summat ratkaisevat voittajan, kun molemmat pelit ovat päättyneet. Vanhoja päättyneitä tietoja ei lasketa uudelleen.

Kun peli päättyy, viimeisessä match-tapahtumassa on myös record eli pelitallenne. Tallenna se sellaisenaan, niin koko peli säilyy. Pelitallenteet

Tilan synkronointi

Jos yhteys katkeaa tai tapahtumia ei tule 15 sekuntiin, yhdistä uudelleen ja pidennä odotusta 1 sekunnista enintään 30 sekuntiin. Ohita vanhemmat tilat. Ihmistä vastaan vertaa järjestyksessä room_created_at, round_no ja revision. Jos siirron vastaus katoaa, lähetä siirto uudelleen vain, jos vuoro ja laudan versio ovat ennallaan.

Lähetä moottorin tiedot toiminnolla agent_environment käynnistyksen yhteydessä ja tietojen muuttuessa. Automaattisessa parituksessa v2 sallii enintään 10 virtayhteyttä eikä yhtään agent_poll-kutsua viimeisten 10 verkossa vietetyn minuutin aikana.

Tunnistautuminen

Käytä HTTPS:ää, JSON POSTia ja Authorization: Bearer -otsaketta. Tunniste koskee yhtä bottia. Älä kirjoita sitä URL-osoitteisiin, julkiseen koodiin tai lokeihin.

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

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

Yhteysohjelman valitsimet

Ohjelman tools/bot_match_client.py valitsimet. Täsmälleen yksi valitsimista --engine ja --nboard / --edax / --egaroucid on pakollinen. Tunniste ei ole koskaan valitsin; se luetaan vain ympäristömuuttujasta FS_BOT_TOKEN. Paluukoodit: 0 normaali pysähdys, 2 tunniste hylätty, 3 --max-runtime saavutettu.

ParametritKuvaus
--engine "COMMAND"Käynnistää komennon kerran peliä kohden ja vaihtaa yhden JSON-rivin siirtoa kohden sulkematta sen syötettä. Yhden rivin vastaava ja sulkeutuva moottori käynnistetään uudelleen seuraavalla siirrolla.
--nboard "COMMAND"Pitää yhden NBoard-moottorin käynnissä peliä kohden, yhteensä kaksi. Vain tavallinen peli (std).
--edax PATHEdax voidaan yhdistää myös pelkällä ohjelmapolulla käyttäen alla olevaa --edax-valintaa. Erillistä sovitinta ei tarvita. Yhdistämisohjelma käynnistää Edaxin xboard-tilassa ja lähettää molempien jäljellä olevat ajat ennen jokaista siirtoa; Edax päättää miettimisajan itse oman kellonsa perusteella (yhdistämisohjelma v1.4.8 tai uudempi). Pelin aikana Edax säilyttää pelinsä ja hash-taulunsa, ja valinnalla --engine-ponder on se hakee myös vastustajan ajalla. --edax-protocol nboard käyttää aiempaa NBoard-yhteyttä.
--edax-eval PATHEdaxin eval.dat-tiedoston polku. Ilman valintaa etsitään data/eval.dat ohjelman kansiosta tai sen yläkansiosta.
--edax-protocol xboard|nboardValinnan --edax yhteystapa. Oletus xboard antaa Edaxin hoitaa oman kellonsa ja ponderoida (v1.4.8 tai uudempi). nboard on versioon v1.4.7 asti käytetty yhteys: yhdistämisohjelma määrää kunkin siirron ajan, eikä Edax ponderoi.
--egaroucid PATHValmistele Egaroucid for Console. Valitse konsoliohjelma ja säilytä resources-kansio paikallaan. macOS- ja Linux-järjestelmissä käytetään virallisten ohjeiden mukaan käännettyä ohjelmaa. Asema ja jäljellä oleva aika välitetään komennoilla setboard, settime ja go ilman sovitinta.
--egaroucid-level NKäytetään yhdessä --egaroucid-valinnan kanssa. Arvot 1:stä 60:een käynnistävät Egaroucidin tällä tasolla (-level N) eivätkä lähetä jäljellä olevaa aikaa (settime); 0 tai puuttuva arvo pitää aikatilan, joka seuraa pelikelloa. Tasotilassa ei ole komentoa haun keskeyttämiseen: jos siirto ylittää --max-think-seconds-rajan, yhteysohjelma pysäyttää moottorin ja pelaa laillisen varasiirron. Valitse taso, joka valmistuu reilusti pelikellon sisällä.
--nboard-depth NLähettää NBoard-moottorille set depth N. Arvo 0:sta 60:een; 0 säilyttää moottorin oletusarvon. Kun mukana on --edax, arvo on Edaxin taso (20 tarkoittaa L20); ilman arvoa taso on 60. Edax pelaa siihen asti parhaan siirron, kun taso saavutetaan tai siirron aika loppuu, kumpi tahansa tulee ensin. Valinnalla --edax arvo lähetetään xboardin kautta muodossa sd N.
--max-think-seconds SEnimmäisaika sekunteina, jonka moottoria odotetaan siirtoa kohden. Oletus 10, enintään 300. Ei koskaan pidempi kuin jäljellä oleva kelloaika miinus 0,75 sekuntia. Tämä on yhteysohjelman turvaraja; palvelimella ei ole siirtokohtaista aikarajaa. Arvo 0 poistaa siirtokohtaisen rajan; käytössä on jäljellä oleva peliaika. Pelikellon päättää sivusto, eikä yhteysohjelma voi muuttaa sitä: bottien väliset ottelut ja automaattiset bottiottelut antavat kummallekin värille 60 sekuntia laudalla, ja suoraan bottiasi haastava ihminen valitsee ajan. Valinnalla --edax Edax päättää siirron ajan oman kellonsa perusteella tämän rajan sisällä; jos raja tulee vastaan, yhdistämisohjelma pelauttaa Edaxilla heti siihen asti parhaan siirron.
--engine-name NAMEBotin tiedoissa ilmoitettava moottorin nimi (enintään 120 merkkiä). Älä sisällytä komentoja tai polkuja.
--engine-threads NMoottorin säikeet pelia kohden , näkyy profiilissa. Valinnoilla --edax ja --egaroucid moottori ajetaan tällä arvolla (oletus 4, jos koneessa on yli 4 loogista suoritinta, muuten 1); valinnalla --engine se lähetetään jokaisessa pyynnössä nimellä engine_threads. Käytä enintään 4 säiettä moottoria kohden ja yhteensä 8 botin kahden samanaikaisen pelin ottelussa. Kun käytössä on --engine/--nboard, puuttuva arvo kysytään. Tausta-ajossa tai ilman käyttäjää tämä valinta on pakollinen.
--engine-hash-mb MBMoottorikohtainen hash-taulun koko megatavuina (MB). Valinnoilla --edax ja --egaroucid taulu asetetaan suurimpaan kahden potenssiin, joka ei ylitä arvoa (Edax -h, Egaroucid -hash), ja tämä koko ilmoitetaan; ilman valintaa Edax käyttää edax.ini-tiedostoa ja Egaroucid 32 MB. Muut moottorit vain ilmoittavat arvon, eikä niiden asetus muutu. Jokaisella moottorilla on oma taulunsa, joten kahta peliä yhtä aikaa pelaava bottiottelu käyttää kaksinkertaisen määrän.
--engine-ponder on|offPonder (haku vastustajan ajalla). Valinnalla --egaroucid arvo on käynnistää Egaroucidin valinnalla -ponder ja ilmoittaa Päällä; se käyttää suoritinta myös vastustajan vuorolla. Valinnalla --edax (yhdistämisohjelma v1.4.8 tai uudempi) arvo on saa Edaxin ponderoimaan xboardin kautta (hard) ja ilmoittaa Päällä; valinnalla --edax-protocol nboard Edax ei ponderoi eikä arvoa on hyväksytä. Muut moottorit vain ilmoittavat todellisen asetuksensa.
--cpu-name NAMEIlmoitettava suorittimen nimi (enintään 120 merkkiä). Tunnistetaan automaattisesti, jos se jätetään pois.
--once-match IDKäsittelee vain tämän ottelun ja sulkeutuu, kun se päättyy (päättynyt, mitätöity, vanhentunut, hylätty). Myös ihmispelien negatiiviset ID:t toimivat. Testeissä yhdistä se valitsimeen --max-runtime.
--max-runtime SSiivoaa moottorit ja sulkeutuu näin monen sekunnin jälkeen (paluukoodi 3).
--save-games DIRTallentaa jokaisen pelin, joka päättyy asetuksen käyttöönoton jälkeen, tiedostoon DIR/games-YYYY-MM.ndjson, yksi pelitallenne riviä kohden (oletuksena pois päältä). Pelit, jotka päättyivät yhteysohjelman ollessa pysäytettynä tai virran ollessa poikki, täydennetään agent_games-toiminnolla uudelleenyhdistettäessä uusimmasta tallennetusta pelistä alkaen. Yksi peli vie noin 4 kt (10×10:ssä noin 6 kt), joten 1 400 peliä päivässä tekee noin 6 Mt päivässä ja 180 Mt kuukaudessa. Poista vanhat kuukausitiedostot itse, kun et enää tarvitse niitä.
--timing-log PATHLisää siirtoa kohden yhden rivin siitä, mihin aika kului (siirron vastaanotto, vapaan haun odotus, moottori, siirron lähetys). Oletuksena pois päältä; palvelimelle ei lähetetä mitään ylimääräistä.
--api URL, --stream-url URLAPI:n ja virran osoitteet. Pidä yleensä oletusarvot. Vain HTTPS hyväksytään, ja koska tunniste lähetetään mukana, virran on oltava API-palvelimella.

Pelimuunnelmat

Botti saa vain ne pelit, jotka on valittu kohdassa Tuetut pelit. Moottoripyyntöjen ja ottelun tilan game_mode kertoo pelin. Palvelin laskee laudan koon, estetyt ruudut ja lailliset ruudut, joten moottorin tarvitsee vain valita saamastaan legal_moves-luettelosta. Älä tuota 10×10-laudan tai klassisen Reversin siirtoja tavallisen 8×8-laudan siirtogeneroinnilla.

Peligame_modeLauta
Standardstd8×8
Antianti8×8
Grand (10x10)grand10×10
Octagonoctagon10×10 (88)
Klassinen Reversireversi8×8

Yhteiset säännöt: Musta (1) siirtää ensin. Molemmat pelit alkavat samasta asemasta vaihdetuin värein ja ovat käynnissä samanaikaisesti. Bottipareissa, kun sinulla ei ole laillista siirtoa, legal_moves saapuu tyhjänä taulukkona ja botin on itse lähetettävä move=-1 (passi). Palvelin ei passaa puolestasi, ja kellosi jatkaa käymistä. Passaaminen, kun laillinen siirto on olemassa, on laitonta. Peli päättyy, kun kumpikaan väri ei voi siirtää. Uusissa kahden pelin otteluissa normaalisti päättyneen pelin tyhjät ruudut lisätään enemmän nappuloita omistavalle värille ja pisteet lasketaan yhteen. Antissa pienempi korjattu yhteistulos voittaa; tasan oleviin nappulamääriin ei lisätä tyhjiä ruutuja. Sama yhteistulos on tasapeli. Kaikki bottipelit alkavat satunnaisesta asemasta, jossa on 12 nappulaa. Kaikissa pelimuodoissa kummallakin botilla on 1 minuutti peliä kohden.

Anti: nappuloiden asettaminen ja kääntäminen toimivat kuten tavallisessa Othellossa. Voittaja on se, jolla on molemmissa peleissä yhteensä vähemmän nappuloita.

10x10: tavalliset säännöt 10×10-laudalla (100 ruutua). Aloitusnappulat ovat neljässä keskiruudussa; bottiparit lisäävät 8 satunnaista siirtoa ja aloittavat 12 nappulasta.

Octagon: sama lauta ja alkuasetelma kuin 10x10:ssä, mutta jokaisen kulman kolme ruutua, yhteensä 12, ovat käyttökelvottomia (88 pelattavaa ruutua). Estetyt ruudut saapuvat ruutunumeroina kentässä blocked_squares ja arvona 0, samana kuin tyhjä, kentässä board. Taulukko ei ole numerojärjestyksessä. Estettyyn ruutuun ei voi pelata, ja nappularivit katkeavat siihen.

Klassinen Reversi: sääntöjen mukaan alkaa tyhjältä laudalta. Niin kauan kuin jokin neljästä keskiruudusta (27, 28, 35, 36) on tyhjä, nappuloita asetetaan vain niihin eikä mitään käännetä. Kun kaikki neljä on täytetty, tavalliset säännöt ovat voimassa. Kukin väri asettaa enintään 32 nappulaa, mukaan lukien neljä ensimmäistä siirtoa. placed laskee kunkin värin tähän mennessä asettamat nappulat; sen avaimet ovat merkkijonot "1" (musta) ja "2" (valkoinen). Bottiparien pelit alkavat, kun palvelin on asettanut 12 nappulaa satunnaisesti, mukaan lukien neljä keskisiirtoa, joten ensimmäisessä pyynnössä placed-arvojen summa on 12 (yleensä {"1":6,"2":6}). Väri, joka on asettanut kaikki 32, saa tyhjän legal_moves-luettelon ja lähettää -1 jokaisella vuorollaan.

Moottoripyyntöjen esimerkit peleittäin

Esimerkkejä ensimmäisestä mustalle tarkoitetusta pyynnöstä, jonka yhteysohjelma lähettää --engine-moottorille, tuotettuna sääntökoodilla. Kaikkien pelimuotojen oikeat pelit alkavat satunnaisesta asemasta, jossa on 12 nappulaa, joten board ja legal_moves vaihtelevat pelistä toiseen. Jotta esimerkit pysyisivät samoina, niiden aloitussiirrot valittiin laudan keskikohdan läheltä. Myös match_id ja kelloarvot ovat oikeissa peleissä erilaiset.

Anti (anti)

Syöte-JSON (yhteysohjelma → sovitin)

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

Vastaus-JSON (sovitin → yhteysohjelma)

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

Syöte-JSON (yhteysohjelma → sovitin)

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

Vastaus-JSON (sovitin → yhteysohjelma)

{"move":13}
Octagon (octagon)

Syöte-JSON (yhteysohjelma → sovitin)

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

Vastaus-JSON (sovitin → yhteysohjelma)

{"move":13}
Klassinen Reversi (reversi)

Syöte-JSON (yhteysohjelma → sovitin)

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

Vastaus-JSON (sovitin → yhteysohjelma)

{"move":18}

Moottoripyynnön kentät

KenttäTyyppiKuvaus
game_modestringYksi seuraavista: std, anti, grand, octagon, reversi. XOT saapuu ihmispeleissä arvona std.
board_sizeinteger 8 | 108, tai 10 peleissä grand ja octagon.
boardinteger[board_size²]Taulukko, jonka pituus on board_size². Luetaan a1:stä oikealle ja sitten seuraava rivi. 0=tyhjä (myös Octagonin estetyt ruudut), 1=musta, 2=valkoinen.
blocked_squaresinteger[]Octagonin käyttökelvottomat ruudut. Muissa peleissä tyhjä taulukko.
placed{"1": integer, "2": integer}Kunkin värin tähän mennessä asettamat nappulat, mukaan lukien satunnaiset aloitussiirrot; avaimet ovat merkkijonot "1" ja "2". Käytetään klassisen Reversin 32 nappulan rajaan.
legal_movesinteger[]Ruudut, joihin saat pelata nyt. Jos tyhjä, vastaa move=-1.
colorinteger 1 | 2Siirtovuorossa oleva väri. 1=musta, 2=valkoinen.
budget_msintegerTähän siirtoon sallittu aika millisekunteina: pienempi arvoista --max-think-seconds ja jäljellä oleva kelloaika miinus 0,75 sekuntia. Yhteysohjelma pysäyttää moottorin, kun aika ylittyy.
remaining_msintegerVärisi jäljellä oleva kelloaika tässä pelissä millisekunteina, kun tällä vuorolla jo käytetty aika on vähennetty.
match_idinteger ≠ 0Ottelun id. Ihmispeleissä negatiivinen (-huoneen numero).
leginteger 0 | 1Pelin numero 0 tai 1. Ihmispeleissä aina 0.
revisionintegerTämän pelin tilanumero. Lähetä se muuttamattomana agent_move-kutsun mukana.
historyarrayTässä pelissä pelatut siirrot. Tee päätös kentän board perusteella.
round_nointeger | nullIhmispelin kierrosnumero. Bottipareissa null.
room_created_atstring | nullIhmispelin huoneen luontiaika. Bottipareissa null.
engine_threadsinteger (optional)Mukana vain, kun yhteysohjelma käynnistettiin valinnalla --engine-threads. Säikeiden määrä, jonka moottori saa käyttää tässä pelissä; mitoita haku sen mukaan.

Toisen botin haastaminen pelimuunnelmaan

Lisää game_mode kutsuun agent_challenge; oletus on std. Molemmilla boteilla on oltava se kentässä supported_games. Katso vastustajan pelit bottisivulta. Jos jommaltakummalta botilta puuttuu peli, vastaus on HTTP 409 ja alla oleva virhe.

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

Rekisteröintilomakkeessa Standard on valmiiksi valittuna, ja vanhat botit, joilla ei ole tallennettua luetteloa, tukevat peliä std. Voit muuttaa luetteloa vain bottisivun kohdassa Hallitse, et koskaan bottitunnisteella (API). Muutos hylätään, kun ottelu on käynnissä tai odottaa hyväksyntää. Tyhjää luetteloa ei voi tallentaa.

Ihmiset rekisteröityjä botteja vastaan

Ihmiset voivat haastaa bottisi missä tahansa sille rekisteröidyssä pelissä. Jos se tukee tavallista peliä, saapua voi sekä STD että XOT. XOT saapuu arvolla game_mode std ja alkaa laudalta, jolla on jo pelattu 8 siirtoa (ne sisältyvät kenttään history). Haastaja valitsee ajan, eikä peliä lasketa vahvuuslukuun. Ihmistä vastaan pelattavassa ottelussa on yksi peli (leg 0) ja negatiivinen match_id. Palvelin hoitaa passit, kun siirtoa ei voi tehdä, joten älä lähetä -1. Verkossa olevat rekisteröidyt botit, joilla automaattinen paritus on päällä, osallistuvat myös tuettuihin STD/XOT-pikapeleihin. Ne ovat jäsenille luokiteltuja ja vieraille luokittelemattomia.

Laittomat siirrot ja aika

Laiton siirto tai vanhentunut revision hylätään vastauksella HTTP 409 (illegal_move, stale_revision, not_your_turn), eikä lauta muutu. Kello käy sillä välin. Yhteysohjelma lähettää saman siirron uudelleen samalla revisionilla, joten ellei moottoria korjata, kyseinen peli hävitään lopulta ajan loppumiseen. Palvelimella ei ole siirtokohtaista rajaa, ja se tarkistaa vain kunkin värin jäljellä olevan kelloajan. 10 sekuntia on yhteysohjelman valitsimen --max-think-seconds oletusarvo.

Ottelusäännöt

Kaikki bottipelit alkavat satunnaisesta asemasta, jossa on 12 nappulaa. Kaksi peliä pelataan samanaikaisesti vaihdetuin värein. Nappuloiden yhteismäärä ratkaisee; Antissa pienempi määrä voittaa.

Kaikissa pelimuodoissa kummallakin botilla on 1 minuutti peliä kohden.

Jos botti ei ole tehnyt ensimmäistä siirtoaan 30 sekunnin kuluessa alusta, ottelu mitätöidään eikä sitä lasketa vahvuuslukuun. Jos toisen botin yhteys katkeaa ottelun aikana yli 30 sekunniksi toisen ollessa yhteydessä, yhteydessä oleva botti voittaa (finish_reason: disconnect) ja tulos lasketaan vahvuuslukuun.

Palvelin laskee FlipSight-botin siirrot kaikissa pelityypeissä. Sekä verkosta että API:n kautta (agent_challenge) tehdyt haasteet hyväksytään, ja palvelin aloittaa ottelun heti, joten pelihuonetta ei tarvitse pitää auki. Jos palvelimen laskenta pysähtyy yli 30 sekunniksi, ottelu mitätöidään (finish_reason: technical) eikä se vaikuta vahvuuslukuun. Muunnelmien laskeminen on raskasta, joten FlipSight-botteja vastaan pelataan kerrallaan enintään 2 muunnelmaottelua. Kun paikat ovat täynnä, saat HTTP 409 ja site bot variant matches are full; yritä hetken päästä uudelleen.

Automaattinen paritus yhdistää botit, joiden tasolukujen ero on enintään 500 yhteisessä pelimuodossa. Yhteysohjelmalla on 120 sekuntia aikaa hyväksyä ottelu. Tulos vaikuttaa tasolukuun. Kohdassa Hallitse voit valita pelimuodot tai poistaa automaattisen parituksen käytöstä. Harjoitusmoottorilla käynnistetty botti (environment.practice on true) jätetään automaattisten otteluiden ulkopuolelle, eivätkä sen ottelut muita botteja vastaan sinä aikana vaikuta vahvuuslukuun.

Ihmisen suora haaste pelataan yhtenä pelinä tavallisessa huoneessa tuetulla pelillä ja ajalla. Palvelin tekee suorista haasteista aina luokittelemattomia. Verkossa olevat rekisteröidyt botit, joilla automaattinen paritus on päällä, osallistuvat myös tuettuihin STD/XOT-pikapeleihin. Ne ovat jäsenille luokiteltuja ja vieraille luokittelemattomia. Rekisteröity botti ottaa vastaan vain niin monta peliä kuin samanaikaisten pelien asetus sallii (oletus 2). Peli ihmistä vastaan ja bottien ottelu (kaksi lautaa) lasketaan kumpikin 1:ksi.

Ottelun kulku

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)

Kaikki bottipelit alkavat satunnaisesta asemasta, jossa on 12 nappulaa. Kaksi peliä pelataan samanaikaisesti vaihdetuin värein. Nappuloiden yhteismäärä ratkaisee; Antissa pienempi määrä voittaa.

Osallistujanumerosi on 0, jos olet bot_a, ja 1, jos olet bot_b. Osallistuja 0 on musta (1) pelissä legs[0] ja valkoinen (2) pelissä legs[1]; osallistujalla 1 päinvastoin. On sinun vuorosi, kun leg.status on active ja leg.turn on sinun värisi. Voit olla vuorossa molemmissa peleissä yhtä aikaa.

Jos sinulla ei ole laillista siirtoa, sinun on itse lähetettävä move -1 (passi); palvelin ei passaa puolestasi. Ihmistä vastaan pelatuissa peleissä palvelin hoitaa passit kuten tavallisissa pelihuoneissa.

Omalla vuorollasi jäljellä oleva aika = clocks_ms[oma värisi - 1] - (server_now_ms - turn_started_ms). clocks_ms on värijärjestyksessä (musta, valkoinen); totals ja winner ovat osallistujajärjestyksessä (winner 0 tai 1, tasapelissä null).

Ruutunumerot

Ruutunumero = rivi × 8 + sarake, joten a1=0, h1=7, a2=8 ja h8=63. Esimerkiksi 19 on d3 ja 37 on f5. board-taulukko käyttää samaa järjestystä: 0=tyhjä, 1=musta, 2=valkoinen.

    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-laudalla (grand, octagon) ruutu = rivi × 10 + sarake. Sarakkeet ovat a:sta j:hin, ja kymmenes rivi kirjoitetaan koordinaateissa 10 tai 0. a1=0, j1=9, a2=10, j10=99 (sama kuin j0). Samalla koordinaatilla on eri numero kullakin laudan koolla: d3 on 19 8×8-laudalla ja 23 10×10-laudalla.

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

Moottorisovitin

FlipSightin bottiyhteysohjelma (Python 3.9+, vain vakiokirjasto) toimii Windowsissa, macOS:ssä ja Linuxissa ja liittää moottorin kahdella tavalla. --engine käynnistää moottorin kerran peliä kohden, lähettää jokaisella siirrolla yhden JSON-rivin ja lukee yhden rivin {"move": ruutu}. Moottori, joka vastaa yhden rivin ja sulkeutuu, toimii yhä, koska se käynnistetään uudelleen seuraavalla siirrolla, mutta syötteen loppuun asti lukeva moottori (sys.stdin.read() ym.) ei koskaan vastaa, joten lue rivi kerrallaan. Pyynnön legal_moves luettelee lailliset ruudut; jos se on tyhjä, vastaa -1. --nboard pitää NBoard-moottorin käynnissä, yhden peliä kohden; hakusyvyys asetetaan --nboard-depth-valinnalla.

Syöte-JSON (yhteysohjelma → sovitin)

Yhteysohjelman valitsimet

API-toiminnot

Vastausesimerkit näyttävät muodon. Kopiointipainike kopioi vain pyynnön eikä kutsu API:a.

POST agent_environment

Ilmoita ympäristö

Ilmoittaa yhdistin-PC:n suorittimen, käyttöjärjestelmän, moottorin nimen, säikeet ja harjoittelutilan (practice). Lähetä se käynnistyksessä ja arvojen muuttuessa. Vastauksessa on oma bottisi.

ParametritTyyppiPakollinenKuvaus
actionstring "agent_environment"PakollinenKutsuttavan toiminnon nimi
environmentobjectPakollinenYhdistin-PC:n suoritin, käyttöjärjestelmä ja moottorin nimi (kukin enintään 120 merkkiä, valinnainen) sekä practice (true tai false, valinnainen). practice true tarkoittaa, että botti harjoittelee: se jätetään automaattisten otteluiden ulkopuolelle, eivätkä sinä aikana pyydetyt tai hyväksytyt bottiottelut vaikuta vahvuuslukuun. Yhdistin lähettää arvon itse, kun se käynnistetään harjoitusmoottorilla. Palvelin muistaa viimeisen arvon, joten kun harjoittelu päättyy, lähetä se ilman practicea tai arvolla false. hash_mb (MB): Moottoria kohti. Syötä käsin, jos yhdistin ei ilmoita arvoa. ponder (true / false / null): Vain näyttötieto. Valitse käsin, jos arvoa ei ilmoiteta. Muuta varsinainen asetus moottorissa.

Pyyntöesimerkki

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

Vastausesimerkki

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

Haasta

Anna target_id (botin numero) tai target_name (botin nimi); ne näkyvät bottisivulla. Sisäänrakennettuja FlipSight-botteja (is_builtin: true) voi haastaa API:n kautta kaikissa pelityypeissä, ja palvelin aloittaa ottelun heti. Jos sisäänrakennettuja botteja vastaan on jo 2 muunnelmaottelua, saat HTTP 409 ja site bot variant matches are full. Jos kohdebotti on kytkenyt "Bottien haasteet" pois bottien hallinnassa, saat HTTP 409 -vastauksen bot does not accept bot challenges. Bottien automaattiset pelit noudattavat silti automaattisen parituksen asetusta.

Voit haastaa saman botin kolme kertaa peräkkäin. Odota viisi minuuttia kolmannen ottelun päättymisestä.

Haasta bottisivulta

ParametritTyyppiPakollinenKuvaus
actionstring "agent_challenge"PakollinenKutsuttavan toiminnon nimi
target_idinteger ≥ 1ValinnainenHaastettavan botin ID
target_namestringValinnainenHaastettavan botin nimi (target_id:n sijaan)
game_modestring std | anti | octagon | grand | reversiValinnainenBottiparin peli. Oletus on std. Molempien bottien on tuettava sitä. Standard / Anti / Octagon / Grand (10x10) / Klassinen Reversi

Pyyntöesimerkki

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

Vastausesimerkki

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

POST agent_accept

Hyväksy

ParametritTyyppiPakollinenKuvaus
actionstring "agent_accept"PakollinenKutsuttavan toiminnon nimi
match_idinteger ≥ 1PakollinenOttelun ID (negatiivinen ihmistä vastaan pelatuissa peleissä)

Pyyntöesimerkki

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

Vastausesimerkki

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

POST agent_reject

Hylkää

ParametritTyyppiPakollinenKuvaus
actionstring "agent_reject"PakollinenKutsuttavan toiminnon nimi
match_idinteger ≥ 1PakollinenOttelun ID (negatiivinen ihmistä vastaan pelatuissa peleissä)

Pyyntöesimerkki

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

Vastausesimerkki

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

POST agent_move

Lähetä siirto

ParametritTyyppiPakollinenKuvaus
actionstring "agent_move"PakollinenKutsuttavan toiminnon nimi
match_idinteger ≠ 0PakollinenOttelun ID (negatiivinen ihmistä vastaan pelatuissa peleissä)
round_nointeger ≥ 0Pakollinen ihmistä vastaanVain ihmistä vastaan: otteluobjektin round_no
room_created_atstringPakollinen ihmistä vastaanVain ihmistä vastaan: otteluobjektin room_created_at
leginteger 0 | 1PakollinenPeli 0 tai 1 (ihmistä vastaan 0)
revisioninteger ≥ 0PakollinenSen pelin revision, jolle siirto laskettiin; 409 stale_revision, jos peli on muuttunut
moveinteger -1..99 | stringPakollinenRuutu 0-(board_size²−1), passi -1 / d3 / D3 / pass
evalnumber -100..100ValinnainenMoottorisi arvio tämän siirron jälkeen nappuloina omalta puoleltasi (+ tarkoittaa, että olet edellä, kaksi desimaalia). Se voi olla enintään pelattavien ruutujen määrä: 8x8:ssa -64:stä 64:ään, 10x10:ssä -100:sta 100:aan ja kahdeksankulmiossa -88:sta 88:aan. Jos jätät sen pois tai lähetät virheellisen arvon, vain arvio jätetään pois ja siirto hyväksytään. Vain bottien väliset ottelut tallentavat sen, kaikki näkevät sen pelin aikana, myös vastustajan botti, ja pelit ihmisiä vastaan jättävät sen huomiotta.

Pyyntöesimerkki

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

Ihmiset rekisteröityjä botteja vastaan

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

Vastausesimerkki

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

POST agent_games

Lataa pelitallenteet

Palauttaa bottisi päättyneet pelit pelitallenteina. Vastaus on NDJSON-muotoinen (Content-Type application/x-ndjson), ja jokaisella rivillä on yksi peli. Mukana ovat bottien väliset ottelut ja pelit ihmisiä vastaan, mutta eivät harjoituspelit eivätkä pelit sivuston omaa othelloclub-tiliä vastaan. Tekniset mitätöinnit ovat mukana arvolla result void.

Tämä pyyntö ei merkitse bottiasi verkossa olevaksi, eikä sitä lasketa API-määrittely v2:n tarkistukseen. Kukin botti saa kutsua sitä kerran 5 sekunnissa; nopeampi kutsu saa vastaukseksi 429 ja retry_after_sec. Lähetä Accept-Encoding: gzip, niin saat pakatun vastauksen.

ParametritTyyppiPakollinenKuvaus
actionstring "agent_games"PakollinenKutsuttavan toiminnon nimi
sinceinteger ≥ 0ValinnainenAikaisin mukaan otettava updated_ms (ms). Oletus 0.
untilinteger ≥ 0ValinnainenMyöhäisin mukaan otettava updated_ms (ms). Oletus: nyt.
maxinteger 1..300ValinnainenPelejä enintään vastausta kohden, 1:stä 300:aan. Oletus 100.
gamesarrayValinnainenMukaan otettavat pelit (std, anti, octagon, grand, reversi). Oletus: kaikki.
orderstring asc | descValinnainenasc: vanhimmat ensin (oletus). desc: uusimmat ensin.

Pyyntöesimerkki

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

Vastausesimerkki

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

Pelitallenteet

Pelitallenne (record) on yksi JSON-objekti yhdestä päättyneestä pelistä. Siinä ovat pelaajat, tulos, vahvuusluvut, avaus ja jokaisen siirron aika bottisi näkökulmasta. Saat saman objektin kahdesta paikasta.

  1. Pelin päättymistapahtuma: Kun peli päättyy, viimeisessä match-tapahtumassa (status finished tai aborted) on record.
  2. agent_games: Palauttaa päättyneet pelit, yksi riviä kohden. Käytä sitä aiempiin ja väliin jääneisiin peleihin.

Siirrot käyttävät sivuston pelinotaatiota. Jokainen siirto on kaksi merkkiä, ja passi on pa. Sarakkeet ovat a:sta j:hin ja rivit 1:stä 9:ään; 10×10-laudalla kymmenes rivi on 0 (j0 on ruutu 99). squares antaa samat siirrot ruutunumeroina (passi -1), ja colors antaa siirron tehneen puolen, B tai W.

Peleistä, jotka päättyvät virran ollessa poikki, ja peleistä ihmisiä vastaan, joiden pelitallenne ei ole vielä valmis, ei tule record-kenttää pelin päättymistapahtumassa. Täytä tällaiset aukot agent_games-toiminnolla seuraavasti.

  1. Aloituskohta: Lähetä uusimman tallentamasi pelitallenteen updated_ms arvona since. since sisältää itse ajankohdan, joten viimeisin pelitallenteesi tulee uudelleen.
  2. Ohita kaksoiskappaleet: Ohita pelitallenne, jonka kind ja id sinulla jo on.
  3. Seuraava sivu: Kutsu uudelleen uusimmalla saamallasi updated_ms-arvolla. Lopeta, kun vastaus ei tuo uusia pelitallenteita.
  4. Muuttuneet pelitallenteet: Peli, joka muuttuu päättymisensä jälkeen, esimerkiksi teknisessä mitätöinnissä, tulee uudelleen uudemmalla updated_ms-arvolla. Korvaa vanha pelitallenne uudella.

agent_games

Pelitallenteen kentät
KenttäTyyppiKuvaus
formatintegerPelitallenteen muodon versio, nyt 1. Versioon 1 voidaan lisätä uusia kenttiä; numero kasvaa vain, kun olemassa olevan kentän merkitys muuttuu.
kindstringbot: bottien välinen ottelu, jossa on kaksi peliä. human: yksi peli ihmistä vastaan.
idintegerBottiottelun tunnus, kun kind on bot, ja pelin tunnus, kun kind on human. kind ja id yhdessä yksilöivät pelitallenteen.
urlstringSivu, jolla pelin voi katsoa uudelleen
room_id, round_nointeger | nullVain pelit ihmistä vastaan: huone ja kierros
game_modestringPeli (std, anti, grand, octagon, reversi)
opening_modestringrandom12: bottien välisen ottelun satunnainen 12 nappulan alku. xot tai std: miten peli ihmistä vastaan alkoi.
board_sizeinteger 8 | 10Ruutuja sivulla, 8 tai 10
time_limit_secintegerSekunnit peliä ja väriä kohden
autobooleanAutomaattisen parituksen luoma
rankedbooleanLasketaanko ottelu vahvuuslukuun
rating_appliedbooleanMuuttiko tulos vahvuuslukuja
statusstringfinished, tai aborted teknisessä mitätöinnissä
finish_reasonstring | nullMiksi peli päättyi: bottien välisissä otteluissa samat arvot kuin state.finish_reason, peleissä ihmistä vastaan pelihuoneen arvo.
resultstringwin, loss, draw tai void bottisi näkökulmasta
started_ms, finished_ms, updated_msinteger | nullAlku- ja päättymisaika (ms); started_ms on null peleissä ihmistä vastaan. updated_ms on hetki, jolloin pelitallenne viimeksi muuttui, yleensä päättymisaika, ja since ja until vertaavat tähän arvoon.
meobjectBottisi: bot_id, name, engine, rating_before, rating_after. engine on alussa ilmoitettu moottorin nimi; molemmat vahvuusluvut ovat null, jos peli ei vaikuttanut vahvuuslukuun.
opponentobjectVastustaja: kind (bot, human tai guest), name, engine, rating_before, rating_after. Botilla on lisäksi bot_id ja builtin, ihmisellä player_id.
discs[integer, integer]Bottisi ja vastustajan pisteet: bottien välisissä otteluissa molempien pelien summa (state.totals), peleissä ihmistä vastaan nappulamäärät.
opening, opening_squares, opening_colorsstring, integer[], stringAvaussiirrot ennen pelejä samalla notaatiolla: satunnainen 12 nappulan alku tai XOT-avaus.
legs[].my_colorstringBottisi väri tässä pelissä, B tai W
legs[].statusstringactive, finished, timeout, stopped
legs[].discs[integer, integer]Nappulamäärät värijärjestyksessä (musta, valkoinen)
legs[].result_discs[integer, integer] (optional)Valinnainen määrätty tulos [musta, valkoinen] pelille, joka hävittiin ajan loppumiseen; summaan lasketaan tämä nappuloiden sijaan. Ajan ylittäneen puolen ja sen vastustajan tulokset: std ja reversi 0 ja 64, grand 0 ja 100, octagon 0 ja 88, anti 64 ja 0. Toinen peli jatkuu, ja summat ratkaisevat voittajan, kun molemmat pelit ovat päättyneet. Vanhoja päättyneitä tietoja ei lasketa uudelleen.
legs[].moves, squares, colorsstring, integer[], stringPelin siirrot avauksen jälkeen: moves merkkijonona, squares numeroina, colors jokaiselle siirrolle B tai W.
legs[].at_ms, used_ms, left_ms(integer | null)[]Jokaiselle siirrolle: milloin se pelattiin (ms), käytetty aika ja siirtäjän jäljellä oleva kelloaika siirron jälkeen. Pelausajat ovat null peleissä ihmisiä vastaan, ja myös tuntemattomat arvot ovat null.
legs[].evals(number | null)[] (optional)Siirtäjän siirron mukana lähettämä arvio nappuloina siirtäjän puolelta. Ilman arviota lähetetyillä siirroilla on null. Kenttä puuttuu, kun yhdelläkään pelin siirrolla ei ollut arviota.

Virheet

Virheet ovat muotoa {"ok": false, "error": "…"}. 401: pysähdy ja tarkista tunniste. 409: tarkista vuoro, revision sekä lailliset siirrot uusimmasta tilastasi (jos olet epävarma, yhdistä virta uudelleen). 410 tarkoittaa, että toiminto on poistettu (agent_poll 2026-11-22 00:00 (UTC+9) alkaen): käytä tapahtumavirtaa. 429 tarkoittaa liian montaa pyyntöä (yli 20 sekunnissa yhdeltä botilta tai 40 sekunnissa kaikilta saman IP-osoitteen boteilta osoitteeseen bot_match_api.php). Kun saat 429:n, 5xx:n tai yhteysvirheen, lähetä sama pyyntö uudelleen 0,2-0,5 sekunnin kuluttua (noudata Retry-After-otsaketta, jos se on annettu) ja pidennä viivettä muutaman yrityksen jälkeen. Älä koskaan lähetä laitonta siirtoa uudelleen.

{"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
Hae tila (poistetaan 2026-11-22)

Poistetaan 2026-11-22 00:00 (UTC+9): sen jälkeen se palauttaa HTTP 410 {"ok": false, "error": "agent_poll was removed; use bot-stream"}. Hae tilasi tapahtumavirrasta ja yhdistä se uudelleen tahdistaaksesi tilan. Siihen asti se vielä vastaa, mutta 2026-11-21 23:40 (UTC+9) alkaen rekisteröity botti, joka on kutsunut sitä viimeisten 10 minuutin aikana, jätetään automaattisen parituksen ulkopuolelle.

API:n toteuttaminen itse
Copyright © Othelloclubthe.othelloclub.com@gmail.com All rights reserved.