API belgeleri

Yeni başlayanlar için adım adım rehber

Gerekenler

  • Bir FlipSight hesabı.
  • Bir bot fotoğrafı: en fazla 5 MB, genişliği ve yüksekliği en az 175 px olan bir GIF, JPG veya PNG dosyası.
  • Botu çalıştıracağın kendi bilgisayarın Botunuzun hamleleri, bağlantı programının çalıştığı bilgisayarda hesaplanır. Aynı motorla bile güç, bilgisayarın performansına ve motor ayarlarına göre değişebilir; bilgisayarı veya ayarları değiştirirseniz puan da buna göre değişebilir.
  • Python 3, bağlantı programını çalıştıran ücretsiz bir program. 3.9 veya sonrası çalışır; 3.11 veya sonrası önerilir. Bunu 5. adımda kontrol edeceksiniz.
  • Kendi bot motorun. Bağlantı programına test için bir alıştırma motoru dahildir.

1. Botunuzu kaydedin

Giriş yapın ve bot sayfasını (othelloclub.com/tr/flipsight/lab) açın. Üstteki Botumu kaydet kutusunda Bot adı (2–24 karakter) alanına bir ad yazın. Desteklenen oyunlar bölümünde şimdilik yalnızca Standart işaretli kalsın. Bot fotoğrafı yükle alanından bir resim seçin, sonra Botumu kaydet düğmesine basın.

Başarılıysa şöyle görünür: Bağlantı belirteci (yalnız bir kez gösterilir) kutusu, fsbm_ ile başlayan uzun bir metinle açılır.

2. Belirteci saklayın

Bu uzun metin belirteçtir, yani yalnızca botunuza ait bir paroladır. Bağlantı programı, bu bot adına konuştuğunu sunucuya bununla kanıtlar. Tamamını kopyalayın ve metin düzenleyici gibi geçici bir yere yapıştırın. Kutuyu kapattıktan sonra aynı belirteci bir daha göremezsiniz.

Belirteci bir parola gibi koruyun. Kimseye göstermeyin ve ekran görüntüsünü paylaşmayın. Kaybederseniz veya biri görürse bot listesinde Yönet bölümünü açın ve Bağlantı belirteci oluştur düğmesine basın. Yeni belirteci aldığınızda eskisi hemen çalışmaz olur.

3. Bağlantı programını indirin

ZIP dosyasını indirmek için Python örneklerini indir düğmesine basın ve dosyayı çıkarın. Bu rehber çıkarılan klasöre "bot klasörü" der. Klasörü masaüstü gibi kolay bulunan bir yere koyun.

Başarılıysa şöyle görünür: bot klasöründe README.md dosyası ve tools klasörü vardır.

4. Bot klasöründe bir terminal açın

Terminal, komut yazdığınız bir penceredir. Sisteminize göre aşağıdaki gibi açın.

macOS: Command+Space tuşlarına basın, Terminal yazın ve açın. cd yazıp bir boşluk bırakın, bot klasörünü pencereye sürükleyin, sonra Enter'a basın.

Linux: dosya yöneticisinde bot klasörüne sağ tıklayın ve "Uçbirimde Aç" (Open in Terminal) seçeneğini seçin. Menü adı dağıtıma göre değişebilir. Böyle bir menü yoksa bir terminal açın ve macOS'taki gibi cd kullanın.

Windows: bot klasörünü Dosya Gezgini'nde açın. Üstteki adres çubuğuna powershell yazın ve Enter'a basın. O klasörde bir PowerShell penceresi açılır.

Kontrol: aşağıdaki komutu yazın ve Enter'a basın. Listede README.md ve tools görünüyorsa başarılıdır. Bu komut macOS, Linux ve Windows PowerShell'de aynıdır.

ls

5. Python'u kontrol edin

Aynı pencerede sisteminize uygun tek komutu kopyalayın, yapıştırın ve Enter'a basın. Her kod kutusunun sağ üstündeki kopyalama düğmesini kullanabilirsiniz.

macOS / Linux

python3 --version

Windows PowerShell

py --version

Başarılıysa şöyle görünür: Python 3.11.9 gibi 3 ile başlayan bir sürüm. 3.9 veya sonrası çalışır. Komut bulunamazsa Python'u aşağıdaki gibi kurun, pencereyi kapatın ve 4. adımdan yeniden başlayın.

macOS: python.org'dan macOS yükleyicisini (.pkg) indirin ve kurun. Sonra Uygulamalar içindeki Python klasöründen Install Certificates.command dosyasını bir kez çalıştırın. Bu, güvenli (HTTPS) bağlantılar için gereken sertifikaları hazırlar.

Linux: python3'ü dağıtımınızın yazılım yöneticisi veya paket yöneticisiyle kurun.

Windows: python.org'dan Python kurulum yöneticisini (Python install manager) kurun.

python.org

6. Belirteci girin

Belirteci bir ortam değişkenine koyun. Ortam değişkeni, yalnızca bu terminal penceresinin içinde var olan geçici bir ayardır. Adı FS_BOT_TOKEN'dır. Aşağıdan sisteminize uygun tek satırlık komutu kopyalayın, yapıştırın ve Enter'a bir kez basın. Ardından Bot token görünür ve girişinizi bekler. Şimdi 2. adımda kopyaladığınız belirteci yapıştırın ve Enter'a basın.

macOS / Linux

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

Windows PowerShell

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

macOS ve Linux'ta yapıştırılan belirteç görünmez, Windows'ta ise karakterleri yerine * görürsünüz. İkisi de normaldir. Belirteç komutun içine yazılmadığı için komut geçmişinde kalmaz. Ayar yalnızca bu pencerede geçerlidir. Pencereyi kapattıysanız veya yeni bir pencere açtıysanız 4. ve 6. adımları tekrarlayın.

PowerShell’de belirteci Ctrl+V ile yapıştırın.

Başarılıysa şöyle görünür: hata olmadan bir sonraki komut için istem geri gelir.

7. Bağlantı programını başlatın

Aynı pencerede aşağıdaki komutu olduğu gibi kopyalayın, yapıştırın ve Enter'a basın. İçindeki dosya adlarını değiştirmeyin. Botunuz alıştırma motoruyla bağlanır. Bu motor çok zayıftır ve numarası en küçük yasal kareye oynar.

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'

Komut çalışırken metin göstermemesi ve komut istemine dönmemesi normaldir. Botunu çevrimiçi tutmak için bu pencereyi açık, bağlantı programını ve motoru çalışır durumda tut; bilgisayarın uykuya geçmesini önle. Bu pencereyi kapatmak veya Ctrl+C tuşlarına basmak iki programı da durdurur ve botun çevrimdışı olur. Yeniden bağlamak için yukarıdaki komutu tekrar çalıştır. Bağlantı programı diğer botlardan gelen maç isteklerini otomatik kabul eder.

Bot alıştırma motoruyla çalıştığı sürece otomatik maç almaz ve diğer botlarla oynadığı maçlar, sizin istedikleriniz de dahil, puana yansımaz. Kendi motorunuzla yeniden başlatın (adım 10); o andan itibaren eşleştirilir ve puan alır.

Başarılıysa şöyle görünür: bot sayfasındaki Kayıtlı botlar listesinde botunuzun adının sağındaki nokta yeşildir. Üzerine gelince Çevrimiçi görünür.

8. İlk oyunla test edin

Bot sayfasında Oynayan botum alanından botunuzu seçin. FlipSight botları listesinden herhangi bir bot seçin, Meydan oku düğmesine basın ve açılan pencerede onaylayın. Tüm oyun türlerinde FlipSight botlarının hamlelerini sunucu hesaplar; oyun odasını açık tutmanız gerekmez.

Başarılıysa şöyle görünür: oyun odasında iki tahta görünür ve botunuzun her sırasında bir taş konur. Alıştırma motoru çok zayıf olduğu için kaybetmek normaldir.

9. Pencere kapanınca da çalışsın (isteğe bağlı)

İlk oyun bitince 7. adımdaki pencerede Ctrl+C ile bağlayıcıyı durdurun. Aşağıdaki komutla aynı pencerede yeniden başlatın. Bilgisayarın uykuya geçmesini önleyin.

macOS / Linux

screen kullanın ve mybot yerine her bot için ayrı bir ad yazın. Başlattıktan sonra Ctrl+A, ardından D tuşuna basıp pencereyi kapatabilirsiniz. Bu botu durdurmak için alttaki komutla oturuma dönüp Ctrl+C tuşlarına basın.

Başlat

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

Durdur

screen -r mybot

Windows PowerShell

Windows: görev çubuğunda simge durumuna küçültülmüş bir pencere belirir ve bot onun içinde çalışır. Şu anki PowerShell penceresini kapatabilirsiniz. Durdurmak için küçültülmüş pencereyi açıp Ctrl+C'ye basın veya o pencereyi kapatın.

Başlat

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. Kendi motorunuza geçin

Bağlantıyı test ettikten sonra kendi motorunuza geçin: Edax veya Egaroucid için aşağıdaki özel seçenekler, diğer uyumlu motorlar için --nboard, kendi motorunuz için JSON kullanın. Belirteç aynı kalır.

Bir varyant oyunu (Anti, 10x10, Octagon, klasik Reversi) Desteklenen oyunlar bölümünde yalnızca motorunuz o oyunun kurallarını biliyorsa işaretleyin. Diğer botlar ve insanlar, işaretli her oyunda botunuza meydan okuyabilir. Değiştirmek için bot listesinde Yönet bölümünü açın, Desteklenen oyunlar seçimini düzenleyin ve Kaydet düğmesine basın. Bir oyun sürerken veya bekleyen bir meydan okuma varken değiştiremezsiniz.

Sık karşılaşılan sorunlar

BelirtiNeden ve çözüm
Bot gri nokta gösteriyor (çevrimdışı).Bağlantı programının penceresinin hâlâ çalıştığını kontrol edin. Pencereyi kapatınca, Ctrl+C'ye basınca veya bilgisayar uyku moduna geçince durur.
Komutun bulunamadığını söylüyor.
command not found / is not recognized
Python kurulu değil veya kurulumdan sonra pencere yeniden açılmadı. 5. adıma bakın, yeni bir pencere açın ve 4. adımdan yeniden başlayın.
Dosyanın açılamadığını söylüyor.
can't open file
Komutu bot klasörünün dışında çalıştırdınız. 4. adımdaki gibi bot klasörüne geçin ve ls ile README.md ve tools'un listelendiğini kontrol edin.
Belirtecin eksik olduğunu söyleyip kapanıyor.
FS_BOT_TOKEN is missing or invalid
Bu pencerede belirteç yok. Yeni bir pencere açtıysanız 6. adımı tekrarlayın.
Belirtecin reddedildiğini söyleyip duruyor.
Bot credential rejected
Belirteç yanlış yapıştırılmış veya eski bir belirteç. Yeni belirteç oluşturduktan veya botu devre dışı bıraktıktan sonra eski belirteç artık çalışmaz. En son belirteçle 6. adımdan yeniden başlayın.
Aynı hata satırı sürekli çıkıyor.
Connection/state error
İnternet bağlantısını kontrol edin. macOS'ta 5. adımdaki Install Certificates.command dosyasını çalıştırdığınızı kontrol edin. Hata yalnızca oyunlar sırasında çıkıyorsa sunucu, motorunuzun hamlesini yasa dışı diye reddediyor olabilir. Bağlantı programı aynı hamleyi yeniden gönderir; bu yüzden motorun düzeltilmesi gerekir.
Meydan okuma düğmesi çalışmıyor veya meydan okuma kabul edilmiyor.Oynayan botum seçimini ve iki botun da çevrimiçi olduğunu kontrol edin. Rakip doğrudan davetleri kabul etmeli ve boş oyun yeri olmalı. Yanıtsız davet 120 saniye sonra sona erer.
Bot hamle yapmıyor, sonra süreden kaybediyor veya oyun iptal ediliyor.
Engine failed for match
Motor zamanında yanıt vermedi veya yanıtı yanlış biçimdeydi. Motor komutunu ve tek satırlık JSON çıktısını kontrol edin. Bir bot başlangıçtan sonraki 30 saniye içinde ilk hamlesini yapmazsa oyun iptal edilir.
Varyant oyun meydan okumaları gelmiyor.Meydan okuma penceresi yalnızca iki botun da desteklediği oyunları listeler. Oyunun botunuzun Desteklenen oyunlar bölümünde işaretli olduğunu ve diğer botun da desteklediğini kontrol edin. --edax veya --nboard ile bağlanan bir botta yalnızca Standart işaretli olmalıdır.

Sözlük

TerimAnlamı
APIProgramların istek ve yanıt göndermesi için üzerinde anlaşılmış bir yol. Bunu bağlantı programı sizin için yapar.
BelirteçYalnızca botunuza ait bir parola. Bağlantı programı hangi bot olduğunu sunucuya bununla kanıtlar.
TerminalKomut yazdığınız bir pencere. Windows'ta PowerShell kullanın.
Ortam değişkeniBir terminal penceresinden başlatılan programlara verilen geçici bir ayar. Pencere kapanınca kaybolur.
JSONVerileri metin olarak yazma biçimi. Örnek: {"move":19}
MotorBir konuma bakıp hamle seçen program.
AdaptörMotorunuzla bağlantı programı arasında veri dönüştüren küçük bir program.
NBoardOthello motorlarının ve tahta programlarının konum ve hamle alışverişi için kullandığı açık bir biçim. NTest gibi bunu destekleyen motorlar adaptör olmadan bağlanır.
Yasal hamleŞu anda oynayabileceğiniz bir kare. Sunucu bunları legal_moves içinde listeler.

Kendi motorunuzu bağlama

Motor başına en fazla 4 iş parçacığı kullanın. Bir bot maçında iki oyun aynı anda oynanır ve toplamda en fazla 8 iş parçacığı kullanılır.

Edax: --edax

Aşağıdaki kurulum ve çalıştırma örneklerinde Edax 4.6 ve Egaroucid for Console 7.8.2 kullanılır.

Edax 4.6 bağlantı programına dahil değildir. Edax 4.6 sayfasındaki Assets bölümünden işletim sistemine uygun dosyayı indir, bot klasörüne koy ve aşağıdaki hazırlık komutlarıyla aç. Windows ve Linux komutları x86-64 bilgisayarlar içindir.

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

Hazırlık (yalnızca ilk sefer)

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

Başlat

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

Hazırlık (yalnızca ilk sefer)

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

Başlat

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 için resmi macOS çalıştırılabilir dosyası yoktur. Aynı sürümden Source code (tar.gz) ve edax-4.6-linux-x86.tar.gz dosyalarını indir. Mac programını kaynak koddan derle; Linux arşivinden yalnızca ortak değerlendirme dosyası data/eval.dat alınır. Xcode Command Line Tools gerekir. Hazırlık komutları kaynak kodu derler.

Hazırlık (yalnızca ilk sefer)

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)

Başlat

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

Edax aşağıdaki --edax seçeneğine yalnızca çalıştırılabilir dosya yolu verilerek de bağlanabilir. Ayrı bağdaştırıcı gerekmez. Bağlayıcı Edax’i xboard ile başlatır ve her hamleden önce iki tarafın kalan süresini gönderir; düşünme süresini Edax kendi saatine göre belirler (bağlayıcı v1.4.8 veya sonrası). Oyun boyunca Edax oyun kaydını ve hash tablosunu korur, --engine-ponder on ile rakibin süresinde de arar. --edax-protocol nboard eski NBoard bağlantısını kullanır.

Komuttaki yolu kendi programınızın tam yoluyla değiştirin. Boşluk içeren yolları çift tırnak içine alın. Değerlendirme dosyası otomatik bulunmazsa --edax-eval ile eval.dat yolunu belirtin.

--edax veya --nboard bağlantısı yalnızca standart 8×8 oyunları oynar. Bu bot için Desteklenen oyunlar bölümünde yalnızca Standart işaretli kalsın. Bir varyant oyunu gelirse bağlantı programı motora sormaz, hamle yapılmaz ve oyun iptal edilir ya da süreden kaybedilir.

Egaroucid: --egaroucid

Egaroucid for Console hazırlayın. Konsol uygulamasını seçin ve resources klasörünü yerinde tutun. macOS ve Linux’ta resmî yönergelere göre derlenmiş programı kullanın. Konum ve kalan süre setboard, settime ve go komutlarıyla gönderilir; bağdaştırıcı gerekmez.

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"

İki kip de yalnızca standart 8×8 destekler; eşzamanlı her oyun için bir motor çalışır. --max-think-seconds hamle güvenlik sınırıdır (varsayılan 10 saniye). Egaroucid sınıra ulaşırsa arama durdurulur, yasal bir yedek hamle oynanır ve motor sonraki tur yeniden başlatılır.

NTest gibi NBoard motorları: --nboard

NBoard, NTest ile kullanılabilen grafik arayüzlü bir Othello programıdır. NBoard protokolü, programın motorlarla iletişim için yayımladığı biçimdir; NTest gibi bu biçimi destekleyen motorları --nboard ile bağlayın. Her oyun için bir motor açık kalır. Edax da bu biçimi destekler, ancak Edax'i yukarıdaki --edax ile bağlayın.

Windows PowerShell

py tools/bot_match_client.py --engine-threads 2 --nboard "path\to\engine.exe"

macOS / Linux

python3 tools/bot_match_client.py --engine-threads 2 --nboard "path/to/engine"

--edax veya --nboard bağlantısı yalnızca standart 8×8 oyunları oynar. Bu bot için Desteklenen oyunlar bölümünde yalnızca Standart işaretli kalsın. Bir varyant oyunu gelirse bağlantı programı motora sormaz, hamle yapılmaz ve oyun iptal edilir ya da süreden kaybedilir.

Kendi yazdığınız motor: JSON ile bağlanın

Bu bölümü yalnızca kendi yazdığınız bir motoru bağlamak istiyorsanız okuyun. Edax, Egaroucid veya bir NBoard motoru kullanıyorsanız yukarıdaki adımlarla işiniz zaten bitmiştir ve bu bölümü atlayabilirsiniz.

Sıra botunuza her geldiğinde bağlantı programı my_adapter.py dosyasını bir kez çalıştırır. Geçerli konumu tek satır olarak verir (taşların yeri, sıranın kimde olduğu, hangi karelerin yasal olduğu, ne kadar süre kaldığı), my_adapter.py tek satırda bir kareyle yanıt verir ve bağlantı programı bu hamleyi sunucuda oynar. my_adapter.py, arada duran ve hamleyi motorunuza soran küçük bir Python dosyasıdır. Sunucu bağlantısını, belirteci ve hamle gönderimini bağlantı programı üstlenir, bu yüzden bu dosya onlarla hiç uğraşmaz.

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

Motorunuz hangi türden?

  • Hamlesini Python koduyla seçen bir motor: aşağıdaki örnek A'yı kullanın.
  • Her çalıştırıldığında tek bir yanıt satırı yazdırıp kapanan bir program dosyası: aşağıdaki örnek B'yi kullanın.
  • Açık kalan ve sürekli komut alışverişi yapan bir program dosyası: NBoard destekliyorsa yukarıdaki --nboard ile bağlayın. Başka bir protokolse örnek B'yi o protokole uyarlayın ve my_adapter.py'nin motoru açık tutup bir döngüde her seferinde bir satır alışverişi yapmasını sağlayın.

Adım 1: yalnızca bağlantıyı denetleyen bir dosya (my_adapter.py)

Bot klasöründe (README.md ve tools'un bulunduğu yer) my_adapter.py adlı bir dosya oluşturun, aşağıdaki kodu olduğu gibi yapıştırın ve kaydedin. Bu dosya hiçbir motor kullanmaz ve yalnızca ilk yasal kareyle yanıt verir. Motorunuzu bağlamadan önce bağlantının çalıştığını doğrulamak için vardır.

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)

Bağlanmadan önce girdi ve çıktıyı kontrol edin

1 numaralı kutudaki komut, örnek konumu doğrudan adaptöre verir. Tek satır yazdırmalıdır: {"move": 19}. Bu satırı gördüğünüzde 2 numaralı kutudaki komut, 6. adımdaki belirtecin bulunduğu pencerede bağlantı programını bu adaptörle başlatır. İki kutuyu ayrı ayrı çalıştırın. Motorunuz bu JSON biçimini kendisi okuyorsa, komutunu doğrudan --engine'den sonra yazabilirsiniz.

1. Adaptörü tek başına deneyin

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. Bağlantı programını adaptörle başlatın

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'

Adım 2: motorunuzu çağıran bir dosyaya geçin

Adım 1 çalıştıktan sonra my_adapter.py dosyasının tüm içeriğini aşağıdaki örnek A veya B ile değiştirin. Yalnızca EDIT ile işaretli satırları değiştirin, gerisini olduğu gibi bırakın. Ardından yukarıdaki test komutu 1'i yeniden çalıştırın ve tek bir yanıt satırının göründüğünü denetleyin. Hamleyi motorunuz seçtiği için 19 dışında bir kare çıkması normaldir.

Örnek A: hamlesini bir Python fonksiyonuyla seçen motor

Bu örnek, hamleyi seçen search fonksiyonunu içeren my_engine.py adlı bir dosya olduğunu varsayar. EDIT 1 yazan yerde dosya adını ve fonksiyon adını, EDIT 2 yazan yerde de fonksiyona verilen değerleri kendi motorunuza göre değiştirin. Fonksiyon kare numarasını (0 ile 63 arası) veya d3 gibi bir koordinatı döndürmelidir.

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)
Örnek B: program dosyası olan bir motor

Bu örnek, programın 64 tahta karakteri, hamle sırası olan taraf ve milisaniye cinsinden düşünme süresi içeren tek bir satır okuduğunu ve D3 gibi tek bir koordinat satırıyla yanıt verdiğini varsayar (. = boş, X = siyah, O = beyaz). Her motorun kendi biçimi vardır, bu yüzden EDIT 1 yazan yerde program dosyasının adını, EDIT 2 yazan yerde motora gönderilen satırı ve EDIT 3 yazan yerde yanıtı okuyan kısmı kendi motorunuza göre değiştirin.

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)

Düşünme süresi: bot oyunlarında her botun oyun başına süresi 1 dakikadır, bu yüzden tek bir hamlede uzun düşünmek kısa sürede süreden kaybettirir. Örneklerdeki think_ms, kalan süreyi (remaining_ms) kalan hamle sayınıza bölerek bu hamlenin süresini belirler. budget_ms bu hamleye harcanacak süre değildir. Bağlantı programının yanıtı beklediği en uzun süredir (varsayılan olarak 10 saniye). Yanıt bundan geç gelirse bot o oyuna devam edemez ve oyunu süreden kaybeder. Bu yüzden motorunuza budget_ms değerini değil, think_ms değerini verin.

Bir şey bozulduğunda: motor çağrısı başarısız olursa örnek dosyalar nedenini my_adapter.log dosyasına yazar ve onun yerine ilk yasal kareyi oynar. Hamleler tuhaf görünüyorsa önce bu dosyayı açın. Bağlantı programı adaptörün hata iletilerini ekranda göstermez. print komutunu yalnızca tek yanıt satırı için kullanın, hata ayıklama metinlerini ise bir dosyaya yazın.

Hız: bağlantı programı her oyun için my_adapter.py'yi çalışır tutar ve her hamlede bir satır gönderir. Örneklerdeki gibi bir satır yanıtlayıp kapanan bir dosya sonraki hamlede yeniden başlatılır, bu yüzden motorunuz da her seferinde yeniden başlar. Motor yavaş açılıyorsa veya önceki hamlelerin çalışmasını sürdürmesi gerekiyorsa my_adapter.py'yi bir döngüye çevirin: bir satır oku, bir satır yanıtla, tekrarla. Girdiyi sonuna kadar okumayın ve her yanıttan sonra flush yapın.

Bu bölümün geri kalanı, bağlantı programı ile my_adapter.py arasında nelerin alınıp verildiğini anlatan başvuru bilgisidir. Yukarıdaki örnek dosyaları olduğu gibi kullanıyorsanız okumanız gerekmez.

Girdi JSON’u (bağlayıcı → adaptör)

Bu, çalıştırılabilir kod değil, bağlayıcının gönderdiği örnek veridir. Python dosyası olarak kaydetmeyin. Oyun sırasında güncel veriler her turda otomatik olarak gönderilir.

Aşağıda standart 8×8 başlangıç konumunun bir örneği var. Gerçek oyunlarda geçerli konumu bağlantı programı doldurur. board, kareleri a1'den sağa doğru, sonra bir sonraki satırı sıralar; 0=boş, 1=siyah, 2=beyaz. color=1 siyah için hamle ister. legal_moves oynayabileceğiniz kareleri listeler. remaining_ms kalan oyun saatidir, budget_ms ise bağlantı programının bu hamlenin yanıtını beklediği en uzun süredir; ikisi de milisaniye cinsindendir (1000 = 1 saniye). Varyant oyunların alanları ve örnekleri aşağıdaki varyant oyunlar bölümündedir.

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

Yanıt JSON’u (adaptör → bağlayıcı)

Aşağıdaki yanıtlardan birini, sonunda satır sonu olan tek bir JSON satırı olarak yazın. move bir kare numarası veya bir koordinattır; büyük/küçük harf fark etmez. 8×8 tahtada d3 = (3−1)×8+3 = 19. Her zaman aldığınız legal_moves içinden seçin. Bot eşleşmelerinde yasal hamle yoksa -1 veya pass gönderin; insanlarla oyunlarda zorunlu pasları sunucu çözer. stdout'a yalnızca yanıt satırını yazın, başka mesaj yazmayın.

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

İsteğe bağlı: yanıta environment ekleyerek motorun gerçek iş parçacığı sayısını, MB cinsinden hash boyutunu ve ponder durumunu bildirin (bağlayıcı v1.4.6 veya üstü). Bağlayıcı yalnızca aralıktaki sayıları ve true/false değerlerini alıp bot bilgisinde gösterir. Kendi adaptörünüz eval eklerse bağlayıcı onu botlar arası maçlarda hamleyle birlikte gönderir (örneğin {"move":19,"eval":1.5}). eval, hamleden sonraki değerlendirmenizdir, sizin tarafınızdan taş cinsindendir ve en fazla oyunun kare sayısı kadardır; --edax, --egaroucid ve NBoard motorları v1.5.3 sürümüne güncelleyince onu kendiliğinden gönderir.

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

Oyunlara göre motor isteği örnekleri

İndirmeler

Python örneklerini indir

GitHub: flipsight-othello-bot-connector

OpenAPI 3.1 JSON

README.md

.zip kılavuz, bağlayıcı ve örnek motoru içerir; .json API belirtimi, .md ise kılavuzdur.

API'yi kendiniz uygulamak

Önce deneme botunun bağlayıcısını durdurun. 6. adımdaki belirteçle akışı açın. Belirteç başına tek bağlantı kullanın. Her satır bir JSON olayı içerir.

Olay akışı

curl -N 'https://othelloclub.com/flipsight_api/bot-stream' \
  -H "Authorization: Bearer $FS_BOT_TOKEN"
Windows PowerShell
curl.exe -N https://othelloclub.com/flipsight_api/bot-stream -H "Authorization: Bearer $env:FS_BOT_TOKEN"

hello sonrasında state gelir. Bu örnekte 2 numaralı botunuz için gereken alanlar gösterilir.

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

İkinci tahtada (leg 1) botunuz siyahtır (1). turn değeri 1 olduğunda legal_moves içinden bir hamle seçip bu tahtanın revision değeriyle gönderin. Gerçek bir hamle için ikinci bir terminalde 6. adımdaki gibi belirteci ayarlayın ve oynanan oyunun değerlerini kullanın.

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

Olay akışı

API'yi kendiniz uygulamak

TürAçıklama
helloBağlantı kuruldu. bot_id botunuzun numarasıdır.
stateEtkin oyun ve davet listesini yenisiyle değiştirin. bot_b sizseniz pending durumundaki daveti agent_accept ile kabul edebilirsiniz.
matchBu id ile eşleşen oyunu güncelleyin. Etkin her tahtada sıranın botunuzda olup olmadığına bakın.
pingHer 10 saniyede bir bağlantı sinyali gelir. Yanıt gerekmez.
closingSunucunun akışı kapatmadan hemen önce gönderdiği son satırdır. reason overflow (gönderilemeyen satırlar birikti) veya server_shutdown ise yeniden bağlanın ve state ile durumu yakalayın. replaced, aynı belirtecin başka bir yerde de kullanıldığı anlamına gelir. Hemen yeniden bağlanmayın: en az 30 saniye bekleyin, tekrarlanırsa daha uzun bekleyin. Her belirteci yalnızca tek bir yerde kullanın.
Maç nesnesi (matches[])
AlanTürAçıklama
idintegerMaç ID'si (insana karşı oyunlarda negatif)
kindstringİnsana karşı oyunlarda human
bot_aintegerKatılımcı 0'ın bot ID'si (insan için 0)
bot_bintegerKatılımcı 1'in bot ID'si (insan için 0)
game_modestringOyun (std, anti, grand, octagon, reversi)
time_limit_secintegerOyun başına, renk başına verilen saniye
statusstringpending, running, finished, aborted, rejected, expired
expires_msintegerKabul için son süre (milisaniye)
rankedbooleanMaçın puanlı olup olmadığı
state.statusstringactive, finished veya aborted
state.game_modestringOyun (std, anti, grand, octagon, reversi)
state.board_sizeinteger 8 | 10Bir kenardaki kare sayısı, 8 veya 10
state.blocked_squaresinteger[]Kullanılamayan kareler (yalnızca Octagon, sırasız)
state.legsarrayOyunlar (botlar arasında 2, insana karşı 1)
state.totals[integer, integer]Katılımcı başına iki oyunun taş toplamları
state.winnerinteger | nullKazanan katılımcı 0 veya 1, beraberlikte null
state.finish_reasonstring | nulldiscs, timeout, double_timeout, disconnect, no_first_move
Oyun nesnesi (state.legs[])
AlanTürAçıklama
boardinteger[64 | 100]64 / 100 hücre, 0=boş 1=siyah 2=beyaz
turnintegerHamle sırası olan renk, 1 (siyah) veya 2 (beyaz)
legal_movesinteger[]Hamle sırası olan rengin yasal kareleri. Bitmiş oyunlarda boş
placed{"1": integer, "2": integer}Renk başına konan taşlar, anahtarlar "1" (siyah) ve "2" (beyaz)
black_participantintegerBu oyunda siyahla oynayan katılımcı
clocks_ms[number, number]Renk sırasına göre kalan süre taban değerleri (siyah, beyaz)
turn_started_msintegerGeçerli sıranın başladığı sunucu zamanı
revisionintegerBu oyun her değiştiğinde 1 artar
statusstringactive, finished, timeout, stopped
historyarrayOynanan hamleler (color, participant, move, at_ms, eval)
discs[integer, integer]Renk sırasına göre taş sayıları (siyah, beyaz)
result_discs[integer, integer] (optional)Süre nedeniyle kaybedilen bir oyun için isteğe bağlı hakem skoru [siyah, beyaz]; toplamda taşlar yerine bu skor kullanılır. Süresi biten taraf ve rakibi için skorlar: std ve reversi 0 ile 64 arası, grand 0 ile 100 arası, octagon 0 ile 88 arası, anti 64 ile 0 arası. Diğer oyun devam eder ve iki oyun bittikten sonra kazananı toplamlar belirler. Daha önce bitmiş kayıtlar yeniden hesaplanmaz.

Bir oyun bittiğinde son match olayı oyun kaydı olan record alanını da taşır. Oyunun tamamını saklamak için onu olduğu gibi kaydedin. Oyun kayıtları

Durum eşitleme

Bağlantı kesilirse veya 15 saniye boyunca olay gelmezse 1 ile 30 saniye arasında giderek artan aralıklarla yeniden bağlanın. Eski durumları atın. İnsanla oyunda sırayla room_created_at, round_no ve revision değerlerini karşılaştırın. Hamlenin yanıtı kaybolursa yalnızca sıra hâlâ sizdeyse ve tahta sürümü aynıysa yeniden gönderin.

Motor bilgilerini başlangıçta ve değiştiklerinde agent_environment ile bildirin. Otomatik eşleşme için v2, çevrimiçi geçen son 10 dakikada en fazla 10 akış bağlantısına ve sıfır agent_poll çağrısına izin verir.

Kimlik doğrulama

HTTPS, JSON POST ve Authorization: Bearer kullanın. Belirteç tek bir bota aittir. URL, herkese açık kod veya günlüklere koymayın.

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

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

Bağlantı programı seçenekleri

tools/bot_match_client.py seçenekleri. --engine ve --nboard / --edax / --egaroucid seçeneklerinden tam olarak biri gereklidir. Belirteç hiçbir zaman seçenek olarak verilmez; yalnızca FS_BOT_TOKEN ortam değişkeninden okunur. Çıkış kodları: 0 normal durma, 2 belirteç reddedildi, 3 --max-runtime süresine ulaşıldı.

ParametrelerAçıklama
--engine "COMMAND"Bu komutu her oyun için bir kez başlatır ve girdisini kapatmadan her hamlede bir JSON satırı alışverişi yapar. Bir satır yanıtlayıp kapanan motor sonraki hamlede yeniden başlatılır.
--nboard "COMMAND"Her oyun için bir NBoard motoru, toplam iki motor açık tutar. Yalnızca standart (std).
--edax PATHEdax aşağıdaki --edax seçeneğine yalnızca çalıştırılabilir dosya yolu verilerek de bağlanabilir. Ayrı bağdaştırıcı gerekmez. Bağlayıcı Edax’i xboard ile başlatır ve her hamleden önce iki tarafın kalan süresini gönderir; düşünme süresini Edax kendi saatine göre belirler (bağlayıcı v1.4.8 veya sonrası). Oyun boyunca Edax oyun kaydını ve hash tablosunu korur, --engine-ponder on ile rakibin süresinde de arar. --edax-protocol nboard eski NBoard bağlantısını kullanır.
--edax-eval PATHEdax eval.dat dosyasının yolu. Belirtilmezse program klasöründe veya üst klasöründe data/eval.dat aranır.
--edax-protocol xboard|nboard--edax için bağlantı yöntemi. Varsayılan xboard, Edax’in kendi saatini yönetmesine ve ponder yapmasına izin verir (v1.4.8 veya sonrası). nboard, v1.4.7’ye kadar kullanılan bağlantıdır: her hamlenin süresini bağlayıcı belirler ve Edax ponder yapmaz.
--egaroucid PATHEgaroucid for Console hazırlayın. Konsol uygulamasını seçin ve resources klasörünü yerinde tutun. macOS ve Linux’ta resmî yönergelere göre derlenmiş programı kullanın. Konum ve kalan süre setboard, settime ve go komutlarıyla gönderilir; bağdaştırıcı gerekmez.
--egaroucid-level N--egaroucid ile kullanılır. 1 ile 60 arası bir değer Egaroucid'i o seviyede başlatır (-level N) ve kalan süreyi (settime) göndermez; 0 veya değer verilmezse oyun saatini izleyen süre modu kalır. Seviye modunda aramayı yarıda durduran bir komut yoktur: bir hamle --max-think-seconds sınırını aşarsa bağlantı programı motoru durdurur ve yedek bir yasal hamle oynar. Oyun saati içinde rahatça biten bir seviye seçin.
--nboard-depth NNBoard motoruna set depth N gönderir. 0 ile 60 arası; 0 motorun varsayılanını korur. --edax ile bu değer Edax seviyesidir (20, L20 demektir); verilmezse seviye 60'tır. Edax, seviyeye ulaştığında ya da hamle süresi bittiğinde, hangisi önce olursa, o ana kadarki en iyi hamleyi oynar. --edax ile değer xboard üzerinden sd N olarak gönderilir.
--max-think-seconds SHer hamlede motoru beklemek için en fazla saniye. Varsayılan 10, en fazla 300. Hiçbir zaman kalan saatten 0,75 saniye eksiğinden uzun olmaz. Bu, bağlantı programının bir güvenlik sınırıdır; sunucuda hamle başına süre sınırı yoktur. 0, hamle başına sınırı kaldırır ve oyunda kalan süreyi kullanır. Oyun saatini site belirler ve bağlantı programı değiştiremez: botlar arası maçlar ve otomatik bot maçları her renge tahta başına 60 saniye verir, botunuza doğrudan meydan okuyan kişi süreyi kendisi seçer. --edax ile Edax, bu sınır içinde hamle süresini kendi saatine göre belirler; sınıra ulaşılırsa bağlayıcı Edax’e o ana kadarki en iyi hamleyi hemen oynatır.
--engine-name NAMEBot bilgisinde bildirilen motor adı (en fazla 120 karakter). Komut veya yol yazmayın.
--engine-threads NMotorun oyun başına kullandığı iş parçacığı sayısı , profilde gösterilir. --edax veya --egaroucid ile motor bu değerle çalışır (bilgisayarda 4’ten fazla mantıksal CPU varsa varsayılan 4, yoksa 1); --engine ile her istekte engine_threads olarak gönderilir. Motor başına en fazla 4, iki oyunun aynı anda oynandığı bir bot maçında toplam en fazla 8 iş parçacığı kullanın. --engine/--nboard ile değer atlanırsa giriş istenir; arka planda veya etkileşimsiz çalıştırmada bu seçenek zorunludur.
--engine-hash-mb MBMotor başına hash tablosu boyutu (MB). --edax veya --egaroucid ile tablo bu değeri aşmayan en büyük ikinin kuvvetine ayarlanır (Edax -h, Egaroucid -hash) ve bu boyut bildirilir; seçenek yoksa Edax edax.ini’yi, Egaroucid 32 MB kullanır. Diğer motorlar değeri yalnızca bildirir, ayarları değişmez. Her motorun kendi tablosu vardır; aynı anda iki oyun oynayan bir bot maçı iki katını kullanır.
--engine-ponder on|offPonder (rakibin süresinde arama). --egaroucid ile on, Egaroucid’i -ponder ile başlatır ve Açık bildirir; rakibin sırasında da CPU kullanır. --edax ile (bağlayıcı v1.4.8 veya sonrası) on, Edax’in xboard üzerinden (hard) ponder yapmasını sağlar ve Açık bildirir; --edax-protocol nboard ile Edax ponder yapmaz ve on kabul edilmez. Diğer motorlar yalnızca gerçek ayarlarını bildirir.
--cpu-name NAMEBildirilecek CPU adı (en fazla 120 karakter). Verilmezse otomatik algılanır.
--once-match IDYalnızca bu maçı işler ve maç sona erince çıkar (finished, aborted, expired, rejected). İnsanlarla oyunların negatif kimlikleri de çalışır. Testlerde --max-runtime ile birlikte kullanın.
--max-runtime SBu kadar saniye sonra motorları kapatır ve çıkar (çıkış kodu 3).
--save-games DIRAçıldıktan sonra biten her oyunu DIR/games-YYYY-MM.ndjson dosyasına, her satırda bir oyun kaydı olarak saklar (varsayılan olarak kapalı). Bağlantı programı durmuşken veya akış kopukken biten oyunlar, yeniden bağlanınca kaydedilen en yeni oyundan başlayarak agent_games ile tamamlanır. Bir oyun yaklaşık 4 KB yer kaplar (10×10'da yaklaşık 6 KB), bu yüzden günde 1.400 oyun günde yaklaşık 6 MB, ayda 180 MB eder. Eski ay dosyalarını artık gerekmediğinde kendiniz silin.
--timing-log PATHHer hamle için zamanın nereye gittiğini gösteren bir satır ekler (hamleyi alma, boş arama bekleme, motor, hamleyi gönderme). Varsayılan olarak kapalıdır; sunucuya fazladan bir şey gönderilmez.
--api URL, --stream-url URLAPI ve akış adresleri. Normalde varsayılanları bırakın. Yalnızca HTTPS kabul edilir ve belirteç de gönderildiği için akış API sunucusunda olmalıdır.

Varyant oyunlar

Bot yalnızca Desteklenen oyunlar bölümünde işaretli oyunları alır. Oyunu, motor isteklerindeki ve maç durumundaki game_mode belirtir. Tahta boyutunu, engelli kareleri ve yasal kareleri sunucu hesaplar; bu yüzden motorun yalnızca aldığı legal_moves içinden seçmesi yeterlidir. 10×10 veya klasik Reversi hamlelerini standart 8×8 hamle üretimiyle üretmeyin.

Oyungame_modeTahta
Standartstd8×8
Antianti8×8
Grand (10x10)grand10×10
Octagonoctagon10×10 (88)
Klasik Reversireversi8×8

Ortak kurallar: Siyah (1) önce oynar. İki oyun da aynı konumdan renkler değiştirilerek başlar ve aynı anda oynanır. Bot eşleşmelerinde yasal hamleniz yoksa legal_moves boş dizi olarak gelir ve bot move=-1 (pas) değerini kendisi göndermelidir. Sunucu sizin yerinize pas geçmez ve saatiniz işlemeye devam eder. Yasal hamle varken pas geçmek yasa dışıdır. Hiçbir renk hamle yapamadığında oyun biter. Yeni iki oyunluk maçlarda normal biten her oyunun boş kareleri daha çok taşı olan renge eklenir ve iki puan toplanır. Anti’de düşük düzeltilmiş toplam kazanır; taş sayıları eşitse boş kareler verilmez. Toplamlar eşitse berabere biter. Tüm bot oyunları 12 taşlı rastgele bir konumdan başlar. Tüm oyun türlerinde her botun oyun başına süresi 1 dakikadır.

Anti: taş koyma ve çevirme standart Othello'daki gibidir. İki oyunda toplam daha az taşı olan taraf kazanır.

10x10: 10×10 tahtada (100 kare) standart kurallar. Başlangıç dizilişi ortadaki dört karedir; bot eşleşmeleri buna 8 rastgele hamle ekler ve 12 taşla başlar.

Octagon: tahta ve başlangıç dizilişi 10x10 ile aynıdır, ama her köşedeki üç kare, toplam 12 kare kullanılamaz (88 oynanabilir kare). Engelli kareler blocked_squares içinde kare numarası olarak, board içinde ise boş kareyle aynı değer olan 0 olarak gelir. Dizi sayı sırasında değildir. Engelli kareye oynayamazsınız ve taş dizileri orada kesilir.

Klasik Reversi: kurallara göre oyun boş tahtadan başlar. Ortadaki dört kareden (27, 28, 35, 36) biri boş olduğu sürece yalnızca oraya taş konur ve hiçbir taş çevrilmez. Dördü de dolunca standart kurallar geçerlidir. Her renk, ilk dört hamle dahil en fazla 32 taş koyar. placed her rengin şimdiye kadar koyduğu taşları sayar; anahtarları "1" (siyah) ve "2" (beyaz) dizgileridir. Bot eşleşmeleri, sunucu ortadaki dört hamle dahil 12 rastgele taş koyduktan sonra başlar; bu yüzden ilk istekte iki placed değerinin toplamı 12 olur (genellikle {"1":6,"2":6}). 32 taşın hepsini koymuş bir renk boş legal_moves alır ve her sırasında -1 gönderir.

Oyunlara göre motor isteği örnekleri

Bağlantı programının bir --engine motoruna gönderdiği, siyah için ilk istek örnekleri; kural koduyla üretilmiştir. Her türden gerçek oyun 12 taşlı rastgele bir konumdan başlar, bu yüzden board ve legal_moves her oyunda farklıdır. Bu örneklerin sabit kalması için açılış hamleleri tahtanın ortasına yakın seçildi. Gerçek oyunlarda match_id ve saat değerleri de farklıdır.

Anti (anti)

Girdi JSON’u (bağlayıcı → adaptör)

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

Yanıt JSON’u (adaptör → bağlayıcı)

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

Girdi JSON’u (bağlayıcı → adaptör)

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

Yanıt JSON’u (adaptör → bağlayıcı)

{"move":13}
Octagon (octagon)

Girdi JSON’u (bağlayıcı → adaptör)

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

Yanıt JSON’u (adaptör → bağlayıcı)

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

Girdi JSON’u (bağlayıcı → adaptör)

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

Yanıt JSON’u (adaptör → bağlayıcı)

{"move":18}

Motor isteği alanları

AlanTürAçıklama
game_modestringstd, anti, grand, octagon, reversi değerlerinden biri. İnsanlarla oyunlarda XOT, std olarak gelir.
board_sizeinteger 8 | 108; grand ve octagon için 10.
boardinteger[board_size²]Uzunluğu board_size² olan dizi. a1'den sağa doğru, sonra bir sonraki satır okunur. 0=boş (Octagon'un engelli kareleri dahil), 1=siyah, 2=beyaz.
blocked_squaresinteger[]Octagon'da kullanılamayan kareler. Diğer oyunlarda boş dizi.
placed{"1": integer, "2": integer}Her rengin şimdiye kadar koyduğu taşlar, rastgele açılış hamleleri dahil; anahtarlar "1" ve "2" dizgileridir. Klasik Reversi'nin 32 taş sınırı için kullanılır.
legal_movesinteger[]Şu anda oynayabileceğiniz kareler. Boşsa move=-1 ile yanıt verin.
colorinteger 1 | 2Hamle sırası olan renk. 1=siyah, 2=beyaz.
budget_msintegerBu hamle için verilen süre, milisaniye cinsinden: --max-think-seconds ile kalan saatten 0,75 saniye eksiğinin küçüğü. Aşılırsa bağlantı programı motoru durdurur.
remaining_msintegerBu oyunda renginizin kalan saati, bu sırada kullanılan süre düşüldükten sonra, milisaniye cinsinden.
match_idinteger ≠ 0Maç kimliği. İnsanlarla oyunlarda negatiftir (-oda numarası).
leginteger 0 | 1Oyun numarası, 0 veya 1. İnsanlarla oyunlarda her zaman 0.
revisionintegerBu oyunun durum numarası. agent_move ile değiştirmeden gönderin.
historyarrayBu oyunda oynanan hamleler. Kararı board'a göre verin.
round_nointeger | nullİnsanla oyunun tur numarası. Bot eşleşmelerinde null.
room_created_atstring | nullİnsanla oyun odasının oluşturulma zamanı. Bot eşleşmelerinde null.
engine_threadsinteger (optional)Yalnızca bağlantı programı --engine-threads ile başlatıldıysa bulunur. Motorun bu oyunda kullanabileceği iş parçacığı sayısı; aramayı buna göre ayarlayın.

Başka bir bota varyant oyunda meydan okumak

agent_challenge isteğine game_mode ekleyin; varsayılanı std'dir. İki botun da supported_games listesinde bu oyun olmalıdır. Rakibin oyunlarına bot sayfasından bakın. Botlardan birinde oyun yoksa yanıt, aşağıdaki hatayla HTTP 409 olur.

{"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 değiştirme

Kayıt formu Standart işaretli olarak başlar; kayıtlı listesi olmayan eski botlar std destekler. Listeyi yalnızca bot web sayfasındaki Yönet bölümünden değiştirebilirsiniz; bot belirteciyle (API) asla değiştiremezsiniz. Bir maç sürerken veya kabul beklerken değişiklik reddedilir. Boş liste kaydedilemez.

İnsanlara karşı kayıtlı botlar

İnsanlar botunuza, kayıtlı olduğu her oyunda meydan okuyabilir. Bot standart oyunu destekliyorsa hem STD hem XOT gelebilir. XOT, game_mode std ile gelir ve 8 hamlenin zaten oynandığı bir tahtadan başlar (bu hamleler history içindedir). Süreyi meydan okuyan kişi seçer ve oyun puanlı değildir. İnsanla oyunun tek bir oyunu (leg 0) ve negatif bir match_id değeri vardır. Hamle mümkün olmadığında pasları sunucu yönetir; bu yüzden -1 göndermeyin. Otomatik eşleştirmesi açık olan çevrimiçi kayıtlı botlar, desteklenen STD/XOT hızlı maçlarına da katılır. Üyelerin hızlı maçları puanlı, misafirlerinki puansızdır.

Yasa dışı hamleler ve süre

Yasa dışı bir hamle veya eskimiş revision, HTTP 409 (illegal_move, stale_revision, not_your_turn) ile reddedilir ve tahta değişmez. Bu sırada saat işlemeye devam eder. Bağlantı programı aynı hamleyi aynı revision ile yeniden gönderir; bu yüzden motor düzeltilmezse o oyun sonunda süreden kaybedilir. Sunucuda hamle başına sınır yoktur, yalnızca her rengin kalan saati kontrol edilir. 10 saniye, bağlantı programının varsayılan --max-think-seconds değeridir.

Maç kuralları

Tüm bot oyunları 12 taşlı rastgele bir konumdan başlar. Renkler değiştirilerek iki oyun aynı anda oynanır. Toplam taş sayısı kazananı belirler; Anti oyununda az taş kazanır.

Tüm oyun türlerinde her botun oyun başına süresi 1 dakikadır.

Bir bot başlangıçtan sonraki 30 saniye içinde ilk hamlesini yapmazsa maç iptal edilir ve puanlanmaz. Maç sırasında bir botun bağlantısı 30 saniyeden uzun süre koparken diğeri bağlıysa bağlı bot kazanır (finish_reason: disconnect) ve sonuç puanlanır.

FlipSight botunun hamlelerini her oyun türünde sunucu hesaplar. Hem web üzerinden hem de API ile (agent_challenge) gelen davetler kabul edilir ve sunucu maçı hemen başlatır; oyun odasını açık tutmanız gerekmez. Sunucunun hesaplaması 30 saniyeden uzun durursa maç iptal edilir (finish_reason: technical) ve puana yansımaz. Varyantları hesaplamak ağır olduğundan FlipSight botlarıyla aynı anda en fazla 2 varyant maçı oynanır. Yerler doluysa HTTP 409 ve site bot variant matches are full döner; biraz sonra yeniden deneyin.

Otomatik eşleştirme, iki botun ortak seçtiği türde puan farkı en fazla 500 olan botları eşleştirir. Bağlantı programının kabul için 120 saniyesi vardır. Sonuç puana işlenir. Yönet menüsünden türleri seçebilir veya eşleştirmeyi kapatabilirsiniz. Alıştırma motoruyla başlatılan bot (environment.practice true) otomatik maçların dışında kalır ve bu sürede diğer botlarla oynadığı maçlar puana yansımaz.

Bir kişinin doğrudan meydan okuması, desteklenen oyun ve süreyle normal odada tek oyun olarak oynanır. Sunucu doğrudan meydan okumaları her zaman puansız yapar. Otomatik eşleştirmesi açık olan çevrimiçi kayıtlı botlar, desteklenen STD/XOT hızlı maçlarına da katılır. Üyelerin hızlı maçları puanlı, misafirlerinki puansızdır. Kayıtlı bir bot yalnızca eşzamanlı oyun ayarının izin verdiği kadar oyun kabul eder (varsayılan 2). İnsana karşı bir oyun ve bir bot maçı (iki tahta) her biri 1 sayılır.

Maç akışı

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)

Tüm bot oyunları 12 taşlı rastgele bir konumdan başlar. Renkler değiştirilerek iki oyun aynı anda oynanır. Toplam taş sayısı kazananı belirler; Anti oyununda az taş kazanır.

bot_a iseniz katılımcı numaranız 0, bot_b iseniz 1'dir. Katılımcı 0, legs[0]'da siyah (1), legs[1]'de beyaz (2) oynar; katılımcı 1 bunun tersidir. leg.status active olduğunda ve leg.turn renginize eşit olduğunda sıra sizdedir. Sıra iki oyunda aynı anda sizde olabilir.

Yasal hamleniz yoksa move -1 (pas) değerini kendiniz göndermelisiniz; sunucu sizin yerinize pas geçmez. İnsana karşı oyunlarda sunucu pasları normal oyun odalarındaki gibi işler.

Sıra sizdeyken kalan süre = clocks_ms[renginiz - 1] - (server_now_ms - turn_started_ms). clocks_ms renk sırasındadır (siyah, beyaz); totals ve winner katılımcı sırasındadır (winner 0 veya 1, beraberlikte null).

Hücre numaraları

Hücre numarası = satır × 8 + sütun; yani a1=0, h1=7, a2=8 ve h8=63. Örneğin 19 d3, 37 ise f5'tir. board dizisi aynı sırayı kullanır: 0=boş, 1=siyah, 2=beyaz.

    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 tahtada (grand, octagon) kare = satır × 10 + sütun. Sütunlar a'dan j'ye kadardır ve onuncu satır koordinatlarda 10 veya 0 olarak yazılır. a1=0, j1=9, a2=10, j10=99 (j0 ile aynı). Aynı koordinatın numarası tahta boyutuna göre farklıdır: d3, 8×8'de 19, 10×10'da 23'tür.

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

Motor adaptörü

FlipSight bot bağlantı programı (Python 3.9+, yalnızca standart kütüphane) Windows, macOS ve Linux'ta çalışır ve motoru iki şekilde bağlar. --engine motoru her oyun için bir kez başlatır, her hamlede bir JSON satırı gönderir ve bir {"move": kare} satırı okur. Bir satır yanıtlayıp kapanan motor, sonraki hamlede yeniden başlatıldığı için çalışmaya devam eder; ancak girdiyi sonuna kadar okuyan motor (sys.stdin.read() vb.) hiç yanıt vermez, bu yüzden her seferinde bir satır okuyun. İstekteki legal_moves yasal kareleri listeler; liste boşsa -1 yanıtlayın. --nboard bir NBoard motorunu her oyun için bir tane olmak üzere çalışır durumda tutar; derinliği --nboard-depth ile ayarlayın.

Girdi JSON’u (bağlayıcı → adaptör)

Bağlantı programı seçenekleri

API işlemleri

Yanıt örnekleri biçimi gösterir. Kopyala düğmesi yalnızca isteği kopyalar ve API'yi çağırmaz.

POST agent_environment

Ortamı bildir

Bağlantı programının çalıştığı bilgisayarın CPU, işletim sistemi, motor adı, iş parçacığı sayısı ve alıştırma durumunu (practice) bildirir. Başlangıçta ve değerler değiştiğinde gönderin. Yanıtta botunuz gelir.

ParametrelerTürZorunluAçıklama
actionstring "agent_environment"ZorunluÇağrılacak işlemin adı
environmentobjectZorunluBağlantı programının çalıştığı bilgisayarın CPU, işletim sistemi ve motor adı (her biri en fazla 120 karakter, isteğe bağlı) ile practice (true veya false, isteğe bağlı). practice true ise bot alıştırma yapıyor demektir: otomatik maçların dışında kalır ve bu sürede istenen veya kabul edilen bot maçları puana yansımaz. Bağlantı programı alıştırma motoruyla başlatıldığında bu değeri kendisi gönderir. Sunucu son değeri hatırlar; alıştırma bitince değeri practice olmadan ya da false ile gönderin. hash_mb (MB): Motor başına. Bağlayıcı değeri bildirmiyorsa elle girin. ponder (true / false / null): Yalnızca gösterim. Değer bildirilmezse elle seçin. Gerçek ayarı motorda değiştirin.

İstek örneği

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

Yanıt örneği

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

Meydan oku

Rakibi target_id (bot numarası) veya target_name (bot adı) ile belirtin; bunlar bot sayfasında görünür. Yerleşik FlipSight botlarına (is_builtin: true) her oyun türünde API ile davet gönderilebilir ve sunucu maçı hemen başlatır. Yerleşik botlarla zaten 2 varyant maçı sürüyorsa HTTP 409 ve site bot variant matches are full döner. Hedef bot, bot yönetiminde "Bot davetleri"ni kapattıysa HTTP 409 ve bot does not accept bot challenges gelir. Botlar arası otomatik maçlar bu ayardan bağımsızdır ve otomatik eşleştirme ayarına göre olur.

Aynı bota art arda üç kez maç isteği gönderebilirsiniz. Üçüncü maç bittiğinde beş dakika bekleyin.

Bot sayfasından meydan oku

ParametrelerTürZorunluAçıklama
actionstring "agent_challenge"ZorunluÇağrılacak işlemin adı
target_idinteger ≥ 1İsteğe bağlıMeydan okunacak botun ID'si
target_namestringİsteğe bağlıMeydan okunacak botun adı (target_id yerine)
game_modestring std | anti | octagon | grand | reversiİsteğe bağlıBot eşleşmesi için oyun. Varsayılanı std. İki bot da desteklemelidir. Standart / Anti / Octagon / Grand (10x10) / Klasik Reversi

İstek örneği

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

Yanıt örneği

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

POST agent_accept

Kabul et

ParametrelerTürZorunluAçıklama
actionstring "agent_accept"ZorunluÇağrılacak işlemin adı
match_idinteger ≥ 1ZorunluMaç ID'si (insana karşı oyunlarda negatif)

İstek örneği

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

Yanıt örneği

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

POST agent_reject

Reddet

ParametrelerTürZorunluAçıklama
actionstring "agent_reject"ZorunluÇağrılacak işlemin adı
match_idinteger ≥ 1ZorunluMaç ID'si (insana karşı oyunlarda negatif)

İstek örneği

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

Yanıt örneği

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

POST agent_move

Hamle gönder

ParametrelerTürZorunluAçıklama
actionstring "agent_move"ZorunluÇağrılacak işlemin adı
match_idinteger ≠ 0ZorunluMaç ID'si (insana karşı oyunlarda negatif)
round_nointeger ≥ 0İnsana karşı oyunda zorunluYalnız insana karşı oyunlar: maç nesnesindeki round_no
room_created_atstringİnsana karşı oyunda zorunluYalnız insana karşı oyunlar: maç nesnesindeki room_created_at
leginteger 0 | 1ZorunluOyun 0 veya 1 (insana karşı oyunlarda 0)
revisioninteger ≥ 0ZorunluHamlenin hesaplandığı oyunun revision değeri; oyun değiştiyse 409 stale_revision
moveinteger -1..99 | stringZorunluHücre 0-(board_size²−1), pas için -1 / d3 / D3 / pass
evalnumber -100..100İsteğe bağlıMotorunuzun bu hamleden sonraki değerlendirmesi, sizin tarafınızdan taş cinsinden (+ öndesiniz demektir, 2 ondalık basamak). Oynanabilir kare sayısına kadar çıkabilir: 8x8'de -64 ile 64, 10x10'da -100 ile 100, sekizgende -88 ile 88 arası. Göndermezseniz ya da değer geçersizse yalnızca değerlendirme atılır ve hamle kabul edilir. Yalnızca botlar arası maçlar onu saklar, oyun sırasında rakip bot dahil herkes görür ve insanlara karşı oyunlar onu yok sayar.

İstek örneği

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

İnsanlara karşı kayıtlı botlar

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

Yanıt örneği

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

POST agent_games

Oyun kayıtlarını indir

Botunuzun biten oyunlarını oyun kayıtları olarak döndürür. Yanıt NDJSON biçimindedir (Content-Type application/x-ndjson) ve her satırda bir oyun bulunur. Botlar arası maçları ve insanlara karşı oyunları içerir, ancak antrenman oyunlarını ve sitenin kendi hesabı othelloclub ile oynanan oyunları içermez. Teknik geçersizlikler result void ile dahil edilir.

Bu istek botunuzu çevrimiçi göstermez ve API belirtimi v2 denetimine sayılmaz. Her bot bunu 5 saniyede bir çağırabilir; daha sık bir çağrı retry_after_sec ile birlikte 429 alır. Sıkıştırılmış yanıt almak için Accept-Encoding: gzip gönderin.

ParametrelerTürZorunluAçıklama
actionstring "agent_games"ZorunluÇağrılacak işlemin adı
sinceinteger ≥ 0İsteğe bağlıDahil edilecek en erken updated_ms, ms cinsinden. Varsayılan 0.
untilinteger ≥ 0İsteğe bağlıDahil edilecek en geç updated_ms, ms cinsinden. Varsayılan: şimdi.
maxinteger 1..300İsteğe bağlıYanıt başına en fazla oyun sayısı, 1 ile 300 arası. Varsayılan 100.
gamesarrayİsteğe bağlıDahil edilecek oyunlar (std, anti, octagon, grand, reversi). Varsayılan: tümü.
orderstring asc | descİsteğe bağlıasc: en eskiler önce (varsayılan). desc: en yeniler önce.

İstek örneği

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

Yanıt örneği

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

Oyun kayıtları

Oyun kaydı (record), biten bir oyunu içeren tek bir JSON nesnesidir. Oyuncuları, sonucu, puanları, açılışı ve her hamlenin zamanını botunuzun tarafından içerir. Aynı nesneyi iki yerden alırsınız.

  1. Oyun bitiş olayı: Bir oyun bittiğinde son match olayı (status finished veya aborted) record taşır.
  2. agent_games: Biten oyunları her satırda bir oyun olarak döndürür. Geçmiş oyunlar ve kaçırdığınız oyunlar için kullanın.

Hamleler sitenin oyun gösterimini kullanır. Her hamle iki karakterdir ve pas pa olarak yazılır. Sütunlar a'dan j'ye, satırlar 1'den 9'a gider; 10×10'da onuncu satır 0'dır (j0, 99 numaralı hücredir). squares aynı hamleleri hücre numarası olarak verir (pas için -1), colors ise hamleyi yapan tarafı B veya W olarak verir.

Akışınız kopukken biten oyunlar ve oyun kaydı henüz hazır olmayan insana karşı oyunlar, oyun bitiş olayında record getirmez. Bu boşlukları aşağıdaki gibi agent_games ile doldurun.

  1. Başlangıç noktası: Kaydettiğiniz en yeni oyun kaydının updated_ms değerini since olarak gönderin. since o zamanı da kapsar, bu yüzden son oyun kaydınız yeniden gelir.
  2. Yinelenenleri atla: kind ve id değerleri sizde zaten olan bir oyun kaydını atlayın.
  3. Sonraki sayfa: Aldığınız en yeni updated_ms ile yeniden çağırın. Bir yanıt yeni oyun kaydı getirmediğinde durun.
  4. Değişen oyun kayıtları: Bittikten sonra değişen bir oyun, örneğin teknik geçersizlikte, daha yeni bir updated_ms ile yeniden gelir. Eski oyun kaydını yenisiyle değiştirin.

agent_games

Oyun kaydı alanları
AlanTürAçıklama
formatintegerOyun kaydı biçiminin sürümü, şu an 1. Sürüm 1'e yeni alanlar eklenebilir; numara yalnızca mevcut bir alanın anlamı değiştiğinde artar.
kindstringbot: iki oyundan oluşan botlar arası maç. human: tek oyunluk insana karşı oyun.
idintegerkind bot için botlar arası maç kimliği, kind human için oyun kimliği. kind ve id birlikte bir oyun kaydını tanımlar.
urlstringOyunu yeniden izleme sayfası
room_id, round_nointeger | nullYalnız insana karşı oyunlar: oda ve tur
game_modestringOyun (std, anti, grand, octagon, reversi)
opening_modestringrandom12: botlar arası maçın 12 taşlı rastgele başlangıcı. xot veya std: insana karşı oyunun nasıl başladığı.
board_sizeinteger 8 | 10Bir kenardaki kare sayısı, 8 veya 10
time_limit_secintegerOyun başına, renk başına verilen saniye
autobooleanOtomatik eşleştirmeyle oluşturuldu
rankedbooleanMaçın puanlı olup olmadığı
rating_appliedbooleanSonucun puanları değiştirip değiştirmediği
statusstringfinished, teknik geçersizlikte aborted
finish_reasonstring | nullOyunun neden bittiği: botlar arası maçlarda state.finish_reason ile aynı değerler, insana karşı oyunlarda oyun odasının değeri.
resultstringBotunuzun tarafından win, loss, draw veya void
started_ms, finished_ms, updated_msinteger | nullBaşlangıç ve bitiş zamanı, ms cinsinden; insana karşı oyunlarda started_ms null olur. updated_ms oyun kaydının son değiştiği zamandır, genellikle bitiş zamanıdır ve since ile until bununla karşılaştırılır.
meobjectBotunuz: bot_id, name, engine, rating_before, rating_after. engine başlangıçta bildirilen motor adıdır; oyun puanlanmadığında iki puan da null olur.
opponentobjectRakip: kind (bot, human veya guest), name, engine, rating_before, rating_after. Botta ayrıca bot_id ve builtin, insanda player_id bulunur.
discs[integer, integer]Botunuzun ve rakibin skoru: botlar arası maçlarda iki oyunun toplamı (state.totals), insana karşı oyunlarda taş sayıları.
opening, opening_squares, opening_colorsstring, integer[], stringOyunlardan önceki açılış hamleleri, aynı gösterimle: 12 taşlı rastgele başlangıç veya XOT açılışı.
legs[].my_colorstringBotunuzun bu oyundaki rengi, B veya W
legs[].statusstringactive, finished, timeout, stopped
legs[].discs[integer, integer]Renk sırasına göre taş sayıları (siyah, beyaz)
legs[].result_discs[integer, integer] (optional)Süre nedeniyle kaybedilen bir oyun için isteğe bağlı hakem skoru [siyah, beyaz]; toplamda taşlar yerine bu skor kullanılır. Süresi biten taraf ve rakibi için skorlar: std ve reversi 0 ile 64 arası, grand 0 ile 100 arası, octagon 0 ile 88 arası, anti 64 ile 0 arası. Diğer oyun devam eder ve iki oyun bittikten sonra kazananı toplamlar belirler. Daha önce bitmiş kayıtlar yeniden hesaplanmaz.
legs[].moves, squares, colorsstring, integer[], stringAçılıştan sonraki oyun hamleleri: moves dize olarak, squares sayı olarak, colors her hamle için B veya W olarak.
legs[].at_ms, used_ms, left_ms(integer | null)[]Her hamle için: ms cinsinden oynandığı zaman, kullanılan süre ve hamleden sonra hamleyi yapan tarafın kalan saati. İnsanlara karşı oyunlarda oynama zamanları null olur, bilinmeyen değerler de null olur.
legs[].evals(number | null)[] (optional)Hamleyi yapan tarafın hamleyle gönderdiği değerlendirme, kendi tarafından taş cinsinden. Değerlendirmesiz gönderilen hamlelerde null olur. Oyundaki hiçbir hamlede değerlendirme yoksa bu alan yer almaz.

Hatalar

Hatalar {"ok": false, "error": "…"} biçimindedir. 401 durumunda durup belirteci kontrol edin. 409 durumunda en son durumunuzda sırayı, revision değerini ve yasal hamleleri kontrol edin (emin değilseniz akışa yeniden bağlanın). 410, işlemin kaldırıldığı anlamına gelir (agent_poll için 2026-11-22 00:00 (UTC+9) itibarıyla): olay akışını kullanın. 429, çok fazla istek (bot_match_api.php'ye tek bottan saniyede 20'den, aynı IP adresindeki tüm botlardan saniyede 40'tan fazla) olduğu anlamına gelir. 429, 5xx ve bağlantı hatalarında aynı isteği 0,2-0,5 sn sonra yeniden gönderin (Retry-After varsa ona uyun) ve birkaç denemeden sonra bekleme süresini artırın. Yasadışı bir hamleyi asla yeniden göndermeyin.

{"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
Durumu al (2026-11-22'de kaldırıldı)

2026-11-22 00:00 (UTC+9) itibarıyla kaldırıldı: o andan sonra HTTP 410 {"ok": false, "error": "agent_poll was removed; use bot-stream"} döndürür. Durumunuzu olay akışından alın; yeniden eşitlemek için akışa yeniden bağlanın. O zamana kadar hâlâ yanıt verir, ancak 2026-11-21 23:40 (UTC+9) itibarıyla son 10 dakikada bunu çağıran kayıtlı bot otomatik eşleştirmenin dışında bırakılır.

API'yi kendiniz uygulamak
Copyright © Othelloclubthe.othelloclub.com@gmail.com All rights reserved.