เอกสาร API

คู่มือทีละขั้นตอนสำหรับมือใหม่

สิ่งที่ต้องมี

  • บัญชี FlipSight
  • รูปบอตหนึ่งรูป: ไฟล์ GIF, JPG หรือ PNG ขนาดไม่เกิน 5 MB กว้างและสูงอย่างน้อย 175 px
  • คอมพิวเตอร์ของคุณสำหรับเปิดใช้งานบอต ตาเดินของบอตคำนวณบนคอมพิวเตอร์ของคุณที่เปิดโปรแกรมเชื่อมต่อไว้ แม้ใช้เอนจินเดียวกัน ความแข็งก็อาจต่างกันตามประสิทธิภาพของคอมพิวเตอร์และการตั้งค่าเอนจิน และถ้าเปลี่ยนคอมพิวเตอร์หรือการตั้งค่า เรตติ้งก็อาจขยับตามไปด้วย
  • Python 3 โปรแกรมฟรีที่ใช้รันตัวเชื่อมต่อ เวอร์ชัน 3.9 ขึ้นไปใช้ได้ แนะนำ 3.11 ขึ้นไป คุณจะตรวจในขั้นตอนที่ 5
  • เอนจินบอตของคุณ โปรแกรมเชื่อมต่อมีเอนจินฝึกหัดสำหรับทดสอบรวมอยู่ด้วย

1. ลงทะเบียนบอต

เข้าสู่ระบบแล้วเปิดหน้าบอต (othelloclub.com/th/flipsight/lab) ในกล่อง ลงทะเบียนบอตของฉัน ด้านบน ใส่ชื่อใน ชื่อบอต (2–24 ตัวอักษร) ตอนนี้ให้ เกมที่รองรับ เลือกไว้เฉพาะ มาตรฐาน เลือกรูปใน อัปโหลดรูปบอต แล้วกดปุ่ม ลงทะเบียนบอตของฉัน

ถ้าสำเร็จจะเห็นแบบนี้: กล่อง โทเคนเชื่อมต่อ (แสดงครั้งเดียว) ปรากฏขึ้นพร้อมข้อความยาวที่ขึ้นต้นด้วย fsbm_

2. เก็บโทเคนไว้

ข้อความยาวนี้คือโทเคน เป็นรหัสผ่านเฉพาะของบอตคุณ ตัวเชื่อมต่อใช้มันยืนยันกับเซิร์ฟเวอร์ว่าทำงานแทนบอตตัวนี้ คัดลอกทั้งหมดแล้ววางเก็บไว้ชั่วคราว เช่น ในโปรแกรมแก้ไขข้อความ เมื่อปิดกล่องแล้ว จะดูโทเคนเดิมอีกไม่ได้

ดูแลโทเคนเหมือนรหัสผ่าน อย่าให้ใครเห็น และอย่าโพสต์ภาพหน้าจอของมัน หากทำหายหรือมีคนเห็น ให้เปิด จัดการ ในรายการบอตแล้วกด สร้างโทเคนเชื่อมต่อ เมื่อได้โทเคนใหม่ โทเคนเก่าจะใช้ไม่ได้ทันที

3. ดาวน์โหลดตัวเชื่อมต่อ

กด ดาวน์โหลดตัวอย่าง Python เพื่อดาวน์โหลดไฟล์ ZIP แล้วแตกไฟล์ คู่มือนี้เรียกโฟลเดอร์ที่แตกออกมาว่า "โฟลเดอร์บอต" วางไว้ในที่ที่หาง่าย เช่น เดสก์ท็อป

ถ้าสำเร็จจะเห็นแบบนี้: ในโฟลเดอร์บอตมีไฟล์ README.md และโฟลเดอร์ tools

4. เปิดเทอร์มินัลในโฟลเดอร์บอต

เทอร์มินัลคือหน้าต่างสำหรับพิมพ์คำสั่ง เปิดตามวิธีของระบบคุณด้านล่าง

macOS: กด Command+Space พิมพ์ Terminal แล้วเปิด พิมพ์ cd และเว้นวรรคหนึ่งครั้ง ลากโฟลเดอร์บอตมาวางในหน้าต่าง แล้วกด Enter

Linux: ในโปรแกรมจัดการไฟล์ คลิกขวาที่โฟลเดอร์บอตแล้วเลือก "เปิดในเทอร์มินัล" (Open in Terminal) ชื่อเมนูอาจต่างกันในแต่ละดิสโทร หากไม่มีเมนูนี้ ให้เปิดเทอร์มินัลแล้วใช้ cd แบบเดียวกับ macOS

Windows: เปิดโฟลเดอร์บอตใน File Explorer พิมพ์ powershell ในแถบที่อยู่ด้านบนแล้วกด Enter หน้าต่าง PowerShell จะเปิดขึ้นในโฟลเดอร์นั้น

ตรวจสอบ: พิมพ์คำสั่งด้านล่างแล้วกด Enter ถ้าเห็น README.md และ tools ในรายการแสดงว่าสำเร็จ คำสั่งนี้เหมือนกันบน macOS, Linux และ Windows PowerShell

ls

5. ตรวจ Python

ในหน้าต่างเดิม คัดลอกคำสั่งของระบบคุณหนึ่งคำสั่ง วางแล้วกด Enter ใช้ปุ่มคัดลอกที่มุมขวาบนของกล่องโค้ดแต่ละกล่องได้

macOS / Linux

python3 --version

Windows PowerShell

py --version

ถ้าสำเร็จจะเห็นแบบนี้: เวอร์ชันที่ขึ้นต้นด้วย 3 เช่น Python 3.11.9 เวอร์ชัน 3.9 ขึ้นไปใช้ได้ หากขึ้นว่าไม่พบคำสั่ง ให้ติดตั้ง Python ตามด้านล่าง ปิดหน้าต่าง แล้วเริ่มใหม่ตั้งแต่ขั้นตอนที่ 4

macOS: ดาวน์โหลดตัวติดตั้งสำหรับ macOS (.pkg) จาก python.org แล้วติดตั้ง จากนั้นรัน Install Certificates.command หนึ่งครั้งจากโฟลเดอร์ Python ใน "แอปพลิเคชัน" ขั้นตอนนี้เตรียมใบรับรองที่จำเป็นสำหรับการเชื่อมต่อแบบปลอดภัย (HTTPS)

Linux: ติดตั้ง python3 ด้วยโปรแกรมจัดการซอฟต์แวร์หรือตัวจัดการแพ็กเกจของดิสโทรคุณ

Windows: ติดตั้ง Python install manager จาก python.org

python.org

6. ใส่โทเคน

ใส่โทเคนลงในตัวแปรสภาพแวดล้อม ซึ่งเป็นการตั้งค่าชั่วคราวที่มีอยู่เฉพาะในหน้าต่างเทอร์มินัลนี้ ชื่อของมันคือ FS_BOT_TOKEN คัดลอกคำสั่งหนึ่งบรรทัดของระบบคุณด้านล่าง วางแล้วกด Enter หนึ่งครั้ง จากนั้นจะขึ้นคำว่า Bot token และรอให้คุณป้อนข้อมูล ตอนนี้ให้วางโทเคนที่คัดลอกไว้ในขั้นตอนที่ 2 แล้วกด Enter

macOS / Linux

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

Windows PowerShell

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

บน macOS และ Linux โทเคนที่วางจะไม่แสดงบนหน้าจอ ส่วนบน Windows จะเห็น * แทนตัวอักษร ทั้งสองแบบเป็นเรื่องปกติ เพราะโทเคนไม่ได้เขียนไว้ในคำสั่ง จึงไม่ค้างอยู่ในประวัติคำสั่ง การตั้งค่านี้มีผลเฉพาะในหน้าต่างนี้ หากปิดหน้าต่างไปแล้วหรือเปิดหน้าต่างใหม่ ให้ทำขั้นตอนที่ 4 และ 6 ซ้ำ

ใน PowerShell ให้กด Ctrl+V เพื่อวางโทเค็น

ถ้าสำเร็จจะเห็นแบบนี้: พรอมต์สำหรับคำสั่งถัดไปกลับมาโดยไม่มีข้อผิดพลาด

7. เริ่มตัวเชื่อมต่อ

ในหน้าต่างเดิม คัดลอกคำสั่งด้านล่างตามที่เป็นอยู่ วางแล้วกด Enter อย่าเปลี่ยนชื่อไฟล์ในคำสั่ง บอตของคุณจะเชื่อมต่อด้วยเอนจินฝึกซ้อม ซึ่งเป็นเอนจินที่อ่อนมาก เดินช่องที่ถูกกติกาซึ่งมีหมายเลขต่ำที่สุด

macOS / Linux

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

Windows PowerShell

py tools/bot_match_client.py --engine-threads 1 --engine 'py tools/bot_match_example_engine.py'

ระหว่างทำงาน คำสั่งไม่แสดงข้อความและไม่กลับไปยังบรรทัดรับคำสั่งถัดไปเป็นเรื่องปกติ เพื่อให้บอตออนไลน์ ให้เปิดหน้าต่างนี้ไว้พร้อมกับโปรแกรมเชื่อมต่อและเอนจินที่ทำงานอยู่ และป้องกันไม่ให้คอมพิวเตอร์เข้าสู่โหมดพัก การปิดหน้าต่างนี้หรือกด Ctrl+C จะหยุดทั้งสองโปรแกรมและทำให้บอตออฟไลน์ หากต้องการกลับมาออนไลน์ ให้เรียกใช้คำสั่งด้านบนอีกครั้ง โปรแกรมเชื่อมต่อจะรับคำขอแข่งขันจากบอตอื่นโดยอัตโนมัติ

ระหว่างที่บอตทำงานด้วยเอนจินฝึกซ้อม จะไม่ถูกจับคู่บอตแข่งอัตโนมัติ และเกมระหว่างบอตที่บอตนั้นเล่น รวมถึงเกมที่คุณท้าเอง จะไม่นำไปคิดเรตติ้ง เมื่อเปลี่ยนเป็นเอนจินของคุณเองแล้วเปิดใหม่ (ขั้นที่ 10) ตั้งแต่นั้นจะถูกจับคู่อัตโนมัติและนำไปคิดเรตติ้ง

ถ้าสำเร็จจะเห็นแบบนี้: ในรายการ บอตที่ลงทะเบียน บนหน้าบอต จุดทางขวาของชื่อบอตคุณเป็นสีเขียว เมื่อวางเมาส์บนจุดจะแสดง ออนไลน์

8. ทดสอบด้วยเกมแรก

บนหน้าบอต เลือกบอตของคุณใน บอตของฉันที่ใช้เล่น เลือกบอตใดก็ได้ในรายการ บอต FlipSight กด ท้าประลอง แล้วยืนยันในหน้าต่างที่เปิดขึ้น ในเกมทุกประเภท เซิร์ฟเวอร์เป็นผู้คำนวณตาเดินของบอต FlipSight จึงไม่ต้องเปิดห้องเกมไว้

ถ้าสำเร็จจะเห็นแบบนี้: ห้องเกมแสดงกระดานสองกระดาน และมีหมากวางลงทุกครั้งที่ถึงตาบอตของคุณ เอนจินฝึกซ้อมอ่อนมาก การแพ้จึงเป็นเรื่องปกติ

9. ให้ทำงานต่อหลังปิดหน้าต่าง (ไม่บังคับ)

เมื่อเกมแรกจบ ให้กด Ctrl+C ในหน้าต่างจากขั้นตอนที่ 7 เพื่อหยุดตัวเชื่อมต่อ แล้วใช้คำสั่งด้านล่างเพื่อเปิดใหม่ในหน้าต่างเดิม อย่าให้คอมพิวเตอร์เข้าสู่โหมดพัก

macOS / Linux

ใช้ screen และเปลี่ยน mybot เป็นชื่อที่ต่างกันสำหรับแต่ละบอต หลังเปิดให้กด Ctrl+A แล้วกด D จากนั้นปิดหน้าต่างได้ เมื่อต้องการหยุดบอตนี้ ให้กลับเข้าเซสชันด้วยคำสั่งด้านล่างแล้วกด Ctrl+C

เริ่ม

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

หยุด

screen -r mybot

Windows PowerShell

Windows: จะมีหน้าต่างที่ย่อไว้ปรากฏบนแถบงาน และบอตทำงานอยู่ในหน้าต่างนั้น ปิดหน้าต่าง PowerShell ปัจจุบันได้ หากต้องการหยุด ให้เปิดหน้าต่างที่ย่อไว้แล้วกด Ctrl+C หรือปิดหน้าต่างนั้น

เริ่ม

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

10. เปลี่ยนเป็นเอนจินของคุณเอง

หลังทดสอบการเชื่อมต่อด้วยเอนจินฝึกซ้อม ให้เปลี่ยนเป็นเอนจินของคุณ ใช้ตัวเลือกเฉพาะด้านล่างสำหรับ Edax หรือ Egaroucid ใช้ --nboard สำหรับเอนจินอื่นที่รองรับ และ JSON สำหรับเอนจินที่เขียนเอง ใช้โทเคนเดิมต่อได้

เลือกเกมรูปแบบอื่น (Anti, 10x10, แปดเหลี่ยม, รีเวอร์ซีคลาสสิก) ใน เกมที่รองรับ เฉพาะเมื่อเอนจินของคุณรู้กติกาของเกมนั้น บอตอื่นและผู้เล่นสามารถท้าบอตของคุณได้ในทุกเกมที่เลือกไว้ หากต้องการเปลี่ยน ให้เปิด จัดการ ในรายการบอต แก้ เกมที่รองรับ แล้วกด บันทึก เปลี่ยนไม่ได้ขณะมีเกมกำลังเล่นหรือมีคำท้ารออยู่

ปัญหาที่พบบ่อย

อาการสาเหตุและวิธีแก้
บอตแสดงจุดสีเทา (ออฟไลน์)ตรวจว่าหน้าต่างตัวเชื่อมต่อยังทำงานอยู่ มันจะหยุดเมื่อปิดหน้าต่าง กด Ctrl+C หรือคอมพิวเตอร์เข้าสู่โหมดสลีป
ขึ้นว่าไม่พบคำสั่ง
command not found / is not recognized
ยังไม่ได้ติดตั้ง Python หรือไม่ได้เปิดหน้าต่างใหม่หลังติดตั้ง ดูขั้นตอนที่ 5 เปิดหน้าต่างใหม่ แล้วเริ่มใหม่ตั้งแต่ขั้นตอนที่ 4
ขึ้นว่าเปิดไฟล์ไม่ได้
can't open file
คุณรันนอกโฟลเดอร์บอต ให้ย้ายไปที่โฟลเดอร์บอตตามขั้นตอนที่ 4 แล้วใช้ ls ตรวจว่ามี README.md และ tools ในรายการ
ขึ้นว่าไม่มีโทเคนแล้วปิดตัวลง
FS_BOT_TOKEN is missing or invalid
หน้าต่างนี้ไม่มีโทเคน หากคุณเปิดหน้าต่างใหม่ ให้ทำขั้นตอนที่ 6 ซ้ำ
ขึ้นว่าโทเคนถูกปฏิเสธแล้วหยุดทำงาน
Bot credential rejected
วางโทเคนผิด หรือเป็นโทเคนเก่า หลังจากออกโทเคนใหม่หรือปิดใช้งานบอต โทเคนเก่าจะใช้ไม่ได้อีก เริ่มใหม่ตั้งแต่ขั้นตอนที่ 6 ด้วยโทเคนล่าสุด
ข้อผิดพลาดบรรทัดเดิมขึ้นซ้ำ ๆ
Connection/state error
ตรวจการเชื่อมต่ออินเทอร์เน็ต บน macOS ให้ตรวจว่าได้รัน Install Certificates.command จากขั้นตอนที่ 5 แล้ว หากขึ้นเฉพาะระหว่างเกม เซิร์ฟเวอร์อาจปฏิเสธตาเดินของเอนจินคุณเพราะผิดกติกา ตัวเชื่อมต่อจะส่งตาเดิมซ้ำ จึงต้องแก้ที่เอนจิน
ปุ่มท้าประลองไม่ทำงาน หรือคำท้าไม่ถูกรับเลือก บอตของฉันที่ใช้เล่น และตรวจสอบว่าบอตทั้งสองออนไลน์ คู่แข่งต้องเปิดรับคำท้าโดยตรงและมีที่ว่างสำหรับเกมใหม่ คำท้าที่ไม่มีการตอบรับจะหมดอายุใน 120 วินาที
บอตไม่เดิน แล้วแพ้เพราะหมดเวลาหรือเกมถูกยกเลิก
Engine failed for match
เอนจินตอบไม่ทันเวลา หรือคำตอบมีรูปแบบผิด ตรวจคำสั่งของเอนจินและเอาต์พุต JSON หนึ่งบรรทัดของมัน หากบอตไม่เดินตาแรกภายใน 30 วินาทีหลังเริ่ม เกมจะถูกยกเลิก
ไม่มีคำท้าเกมรูปแบบอื่นเข้ามาหน้าต่างท้าประลองแสดงเฉพาะเกมที่บอตทั้งสองรองรับ ตรวจว่าได้เลือกเกมนั้นใน เกมที่รองรับ ของบอตคุณ และบอตอีกฝ่ายก็รองรับด้วย บอตที่เชื่อมต่อผ่าน --edax หรือ --nboard ควรเลือกไว้เฉพาะ มาตรฐาน

อภิธานศัพท์

คำศัพท์ความหมาย
APIวิธีที่ตกลงกันไว้สำหรับให้โปรแกรมส่งคำขอและคำตอบถึงกัน ตัวเชื่อมต่อจัดการให้คุณ
โทเคนรหัสผ่านเฉพาะของบอตคุณ ตัวเชื่อมต่อใช้มันยืนยันกับเซิร์ฟเวอร์ว่าเป็นบอตตัวไหน
เทอร์มินัลหน้าต่างสำหรับพิมพ์คำสั่ง บน Windows ให้ใช้ PowerShell
ตัวแปรสภาพแวดล้อมการตั้งค่าชั่วคราวที่ส่งให้โปรแกรมที่เริ่มจากหน้าต่างเทอร์มินัลหนึ่ง จะหายไปเมื่อปิดหน้าต่าง
JSONรูปแบบการเขียนข้อมูลเป็นข้อความ ตัวอย่าง: {"move":19}
เอนจินโปรแกรมที่ดูตำแหน่งบนกระดานแล้วเลือกตาเดิน
อะแดปเตอร์โปรแกรมเล็ก ๆ ที่แปลงข้อมูลระหว่างเอนจินของคุณกับตัวเชื่อมต่อ
NBoardรูปแบบเปิดที่เอนจินและโปรแกรมกระดานโอเทลโลใช้แลกเปลี่ยนตำแหน่งและตาเดิน เอนจินที่รองรับ เช่น NTest เชื่อมต่อได้โดยไม่ต้องใช้อะแดปเตอร์
ตาที่ถูกกติกาช่องที่คุณเดินได้ตอนนี้ เซิร์ฟเวอร์ระบุไว้ใน legal_moves

เชื่อมต่อเอนจินของคุณ

ใช้ไม่เกิน 4 เธรดต่อเอนจิน แมตช์บอตเล่นสองเกมพร้อมกัน จึงใช้รวมไม่เกิน 8 เธรดต่อแมตช์

Edax: --edax

ตัวอย่างการติดตั้งและเริ่มใช้งานด้านล่างใช้ Edax 4.6 และ Egaroucid for Console 7.8.2

โปรแกรมเชื่อมต่อไม่ได้รวม Edax 4.6 ให้ดาวน์โหลดไฟล์สำหรับระบบของคุณจาก Assets ที่ Edax 4.6 วางในโฟลเดอร์บอต แล้วแตกไฟล์ด้วยคำสั่งเตรียมด้านล่าง คำสั่ง Windows และ Linux ใช้กับคอมพิวเตอร์ x86-64

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

เตรียม (ครั้งแรกเท่านั้น)

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

เริ่ม

py tools/bot_match_client.py --engine-threads 2 --edax "edax-4.6\wEdax-x86-64.exe"

Linux (x86-64): edax-4.6-linux-x86.tar.gz

เตรียม (ครั้งแรกเท่านั้น)

mkdir -p edax-4.6
tar -xzf edax-4.6-linux-x86.tar.gz -C edax-4.6
chmod +x edax-4.6/lEdax-x86-64

เริ่ม

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

macOS: edax-reversi-4.6.tar.gz

Edax 4.6 ไม่มีไฟล์โปรแกรม macOS อย่างเป็นทางการ ให้ดาวน์โหลด Source code (tar.gz) และ edax-4.6-linux-x86.tar.gz จากรุ่นเดียวกัน แล้วคอมไพล์โปรแกรม Mac จากซอร์ส ส่วนไฟล์ Linux ใช้ดึงเฉพาะไฟล์ประเมินร่วม data/eval.dat ต้องมี Xcode Command Line Tools คำสั่งเตรียมจะคอมไพล์ซอร์ส

เตรียม (ครั้งแรกเท่านั้น)

xcode-select --install
tar -xzf edax-reversi-4.6.tar.gz
mv edax-reversi-4.6 edax-4.6
mkdir -p edax-4.6/bin
tar -xzf edax-4.6-linux-x86.tar.gz -C edax-4.6 data/eval.dat
(cd edax-4.6/src && make build ARCH=native OS=osx)

เริ่ม

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

Edax เชื่อมต่อได้โดยระบุเพียงพาธไฟล์โปรแกรมด้วย --edax ตามด้านล่าง ไม่ต้องสร้างอะแดปเตอร์แยก ตัวเชื่อมต่อจะเปิด Edax ผ่าน xboard และส่งเวลาที่เหลือของทั้งสองฝ่ายก่อนทุกตา Edax กำหนดเวลาคิดเองตามนาฬิกาของตัวเอง (ตัวเชื่อมต่อ v1.4.8 ขึ้นไป) ระหว่างเกม Edax เก็บประวัติเกมและตารางแฮชไว้ และเมื่อใช้ --engine-ponder on จะค้นหาในเวลาของคู่แข่งด้วย --edax-protocol nboard ใช้การเชื่อมต่อแบบ NBoard แบบเดิม

เปลี่ยนพาธในคำสั่งเป็นพาธเต็มของไฟล์โปรแกรมคุณ หากพาธมีช่องว่างให้ครอบด้วยเครื่องหมายอัญประกาศคู่ ถ้าหาไฟล์ประเมินไม่พบอัตโนมัติ ให้ระบุพาธ eval.dat ด้วย --edax-eval

การเชื่อมต่อด้วย --edax หรือ --nboard เล่นได้เฉพาะเกมมาตรฐาน 8×8 ให้เลือกเฉพาะ มาตรฐาน ใน เกมที่รองรับ ของบอตนี้ หากมีเกมรูปแบบอื่นเข้ามา ตัวเชื่อมต่อจะไม่ถามเอนจิน จะไม่มีการเดิน และเกมจะถูกยกเลิกหรือแพ้เพราะหมดเวลา

Egaroucid: --egaroucid

เตรียม Egaroucid for Console เลือกไฟล์โปรแกรมคอนโซลและเก็บโฟลเดอร์ resources ไว้ที่เดิม บน macOS และ Linux ให้ใช้โปรแกรมที่สร้างตามคู่มือทางการ โปรแกรมเชื่อมต่อส่งกระดานและเวลาที่เหลือด้วย setboard, settime และ go จึงไม่ต้องเขียนอะแดปเตอร์

Egaroucid for Console

Windows PowerShell

py tools/bot_match_client.py --engine-threads 2 --egaroucid "egaroucid\Egaroucid_for_console.exe"

macOS / Linux

python3 tools/bot_match_client.py --engine-threads 2 --egaroucid "egaroucid/bin/Egaroucid_for_Console.out"

ทั้งสองวิธีรองรับเฉพาะเกมปกติ 8×8 และใช้เอนจินแยกเกมละหนึ่งตัวเมื่อเล่นสองเกมพร้อมกัน --max-think-seconds คือขีดจำกัดความปลอดภัยต่อตา (ค่าเริ่มต้น 10 วินาที) ถ้า Egaroucid ถึงขีดจำกัด จะหยุดค้นหา เดินตาสำรองที่ถูกกติกา แล้วเริ่มเอนจินใหม่ในตาถัดไป

เอนจิน NBoard เช่น NTest: --nboard

NBoard เป็นโปรแกรมหน้าจอ Othello ที่ใช้ร่วมกับ NTest ได้ โปรโตคอล NBoard คือรูปแบบสื่อสารแบบเปิดระหว่างโปรแกรมนี้กับเอนจิน เอนจินที่รองรับ เช่น NTest ให้เชื่อมต่อด้วย --nboard โดยเปิดเอนจินค้างไว้เกมละหนึ่งตัว Edax ก็รองรับเช่นกัน แต่ให้เชื่อมต่อ Edax ด้วย --edax ด้านบน

Windows PowerShell

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

macOS / Linux

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

การเชื่อมต่อด้วย --edax หรือ --nboard เล่นได้เฉพาะเกมมาตรฐาน 8×8 ให้เลือกเฉพาะ มาตรฐาน ใน เกมที่รองรับ ของบอตนี้ หากมีเกมรูปแบบอื่นเข้ามา ตัวเชื่อมต่อจะไม่ถามเอนจิน จะไม่มีการเดิน และเกมจะถูกยกเลิกหรือแพ้เพราะหมดเวลา

เอนจินที่เขียนเอง: เชื่อมต่อผ่าน JSON

อ่านส่วนนี้เฉพาะเมื่อคุณต้องการเชื่อมต่อเอนจินที่คุณเขียนเอง หากคุณใช้ Edax, Egaroucid หรือเอนจิน NBoard คุณทำเสร็จแล้วตั้งแต่ด้านบนและข้ามส่วนนี้ได้เลย

ทุกครั้งที่ถึงตาบอตของคุณ ตัวเชื่อมต่อจะรัน my_adapter.py หนึ่งครั้ง โดยส่งตำแหน่งปัจจุบันให้เป็นหนึ่งบรรทัด (หมากอยู่ตรงไหน ถึงตาใคร ช่องไหนเดินได้ถูกกติกา เหลือเวลาเท่าไร) จากนั้น my_adapter.py ตอบกลับเป็นช่องหนึ่งช่องในหนึ่งบรรทัด แล้วตัวเชื่อมต่อจะเดินตานั้นบนเซิร์ฟเวอร์ my_adapter.py เป็นไฟล์ Python เล็ก ๆ ที่อยู่ตรงกลาง ทำหน้าที่ถามตาเดินจากเอนจินของคุณ ตัวเชื่อมต่อดูแลการเชื่อมต่อเซิร์ฟเวอร์ โทเคน และการส่งตาเดินให้ทั้งหมด ไฟล์นี้จึงไม่ต้องยุ่งกับเรื่องเหล่านั้นเลย

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

เอนจินของคุณเป็นแบบไหน

  • เอนจินที่เลือกตาเดินด้วยโค้ด Python: ใช้ตัวอย่าง A ด้านล่าง
  • ไฟล์โปรแกรมที่พิมพ์คำตอบหนึ่งบรรทัดแล้วปิดตัวทุกครั้งที่รัน: ใช้ตัวอย่าง B ด้านล่าง
  • ไฟล์โปรแกรมที่เปิดค้างไว้และแลกคำสั่งกันต่อเนื่อง: ถ้ารองรับ NBoard ให้เชื่อมต่อด้วย --nboard ด้านบน ถ้าเป็นโปรโตคอลอื่น ให้แก้ตัวอย่าง B ให้เข้ากับโปรโตคอลนั้น และให้ my_adapter.py เปิดเอนจินค้างไว้แล้วแลกทีละบรรทัดเป็นวงวน

ขั้นตอนที่ 1: ไฟล์ที่ตรวจการเชื่อมต่ออย่างเดียว (my_adapter.py)

ในโฟลเดอร์บอต (ที่มี README.md และ tools) ให้สร้างไฟล์ชื่อ my_adapter.py วางโค้ดด้านล่างลงไปตามเดิมโดยไม่ต้องแก้ แล้วบันทึก ไฟล์นี้ไม่ใช้เอนจินใดเลย และตอบด้วยช่องที่ถูกกติกาช่องแรกเท่านั้น มีไว้เพื่อยืนยันว่าการเชื่อมต่อใช้งานได้ก่อนที่คุณจะต่อเอนจินของคุณ

import json
import sys

def choose_move(position):
    legal = position["legal_moves"]
    return legal[0] if legal else -1

line = sys.stdin.readline()
position = json.loads(line)
move = choose_move(position)
print(json.dumps({"move": move}), flush=True)

ตรวจอินพุตและเอาต์พุตก่อนเชื่อมต่อ

คำสั่งในกล่อง 1 ส่งตำแหน่งตัวอย่างเข้าอะแดปเตอร์โดยตรง ผลที่ควรได้คือหนึ่งบรรทัด: {"move": 19} เมื่อเห็นบรรทัดนั้นแล้ว คำสั่งในกล่อง 2 จะเริ่มตัวเชื่อมต่อพร้อมอะแดปเตอร์นี้ ให้รันในหน้าต่างที่มีโทเคนจากขั้นตอนที่ 6 รันสองกล่องนี้แยกกัน หากเอนจินของคุณอ่านรูปแบบ JSON นี้ได้เอง ก็ใส่คำสั่งของเอนจินต่อท้าย --engine ได้เลย

1. ทดสอบอะแดปเตอร์อย่างเดียว

macOS / Linux

printf '%s\n' '{"board":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,2,1,0,0,0,0,0,0,1,2,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"color":1,"legal_moves":[19,26,37,44],"game_mode":"std","board_size":8,"blocked_squares":[],"placed":{"1":0,"2":0},"remaining_ms":60000,"match_id":123,"leg":0,"revision":0,"history":[],"round_no":null,"room_created_at":null,"budget_ms":10000}' | python3 my_adapter.py

Windows PowerShell

'{"board":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,2,1,0,0,0,0,0,0,1,2,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"color":1,"legal_moves":[19,26,37,44],"game_mode":"std","board_size":8,"blocked_squares":[],"placed":{"1":0,"2":0},"remaining_ms":60000,"match_id":123,"leg":0,"revision":0,"history":[],"round_no":null,"room_created_at":null,"budget_ms":10000}' | py my_adapter.py

2. เริ่มตัวเชื่อมต่อพร้อมอะแดปเตอร์

macOS / Linux

python3 tools/bot_match_client.py --engine-threads 2 --engine 'python3 my_adapter.py'

Windows PowerShell

py tools/bot_match_client.py --engine-threads 2 --engine 'py my_adapter.py'

ขั้นตอนที่ 2: เปลี่ยนเป็นไฟล์ที่เรียกเอนจินของคุณ

เมื่อขั้นตอนที่ 1 ใช้งานได้แล้ว ให้แทนที่เนื้อหาทั้งหมดของ my_adapter.py ด้วยตัวอย่าง A หรือ B ด้านล่าง แก้เฉพาะบรรทัดที่มีคำว่า EDIT และปล่อยส่วนที่เหลือไว้ตามเดิม จากนั้นรันคำสั่งทดสอบ 1 ด้านบนอีกครั้ง แล้วตรวจว่ามีคำตอบหนึ่งบรรทัดปรากฏขึ้น ตาเดินนี้เอนจินของคุณเป็นผู้เลือก จึงเป็นเรื่องปกติที่จะได้ช่องอื่นที่ไม่ใช่ 19

ตัวอย่าง A: เอนจินที่เลือกตาเดินด้วยฟังก์ชัน Python

ตัวอย่างนี้สมมติว่ามีไฟล์ชื่อ my_engine.py ซึ่งมีฟังก์ชัน search ที่เลือกตาเดิน ที่ EDIT 1 ให้เปลี่ยนชื่อไฟล์และชื่อฟังก์ชัน และที่ EDIT 2 ให้เปลี่ยนค่าที่ส่งเข้าไป ให้ตรงกับเอนจินของคุณ ฟังก์ชันควรคืนค่าเป็นหมายเลขช่อง (0 ถึง 63) หรือพิกัด เช่น d3

import json
import sys
from pathlib import Path

from my_engine import search  # EDIT 1: your engine file and function name


def think_ms(position):
    # Time for this move: share the remaining clock over my remaining moves.
    my_moves_left = position["board"].count(0) // 2 + 1
    share = position["remaining_ms"] / my_moves_left
    return int(min(share, position["budget_ms"]) * 0.8)


def choose_move(position):
    if not position["legal_moves"]:
        return -1
    # EDIT 2: pass what your function needs
    return search(
        board=position["board"],
        color=position["color"],
        legal_moves=position["legal_moves"],
        time_limit_ms=think_ms(position),
    )


position = json.loads(sys.stdin.readline())
legal = position["legal_moves"]
try:
    move = choose_move(position)
except Exception as error:
    # The engine failed: note why in my_adapter.log and play the first legal square.
    with open(Path(__file__).with_name("my_adapter.log"), "a") as log:
        log.write(repr(error) + "\n")
    move = legal[0] if legal else -1
print(json.dumps({"move": move}), flush=True)
ตัวอย่าง B: เอนจินที่เป็นไฟล์โปรแกรม

ตัวอย่างนี้สมมติว่าโปรแกรมอ่านหนึ่งบรรทัดที่มีอักขระกระดาน 64 ตัว ฝ่ายที่ถึงตาเดิน และเวลาคิดเป็นมิลลิวินาที แล้วตอบเป็นพิกัดหนึ่งบรรทัด เช่น D3 (. = ว่าง, X = ดำ, O = ขาว) เอนจินแต่ละตัวมีรูปแบบของตัวเอง จึงให้เปลี่ยนชื่อไฟล์โปรแกรมที่ EDIT 1 บรรทัดที่ส่งให้เอนจินที่ EDIT 2 และส่วนที่อ่านคำตอบที่ EDIT 3 ให้ตรงกับเอนจินของคุณ

my_adapter.py → my_engine

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

my_engine → my_adapter.py

D3
import json
import subprocess
import sys
from pathlib import Path

# EDIT 1: your engine program file (kept in the same folder as my_adapter.py)
ENGINE = Path(__file__).with_name("my_engine.exe" if sys.platform == "win32" else "my_engine")


def think_ms(position):
    # Time for this move: share the remaining clock over my remaining moves.
    my_moves_left = position["board"].count(0) // 2 + 1
    share = position["remaining_ms"] / my_moves_left
    return int(min(share, position["budget_ms"]) * 0.8)


def choose_move(position):
    if not position["legal_moves"]:
        return -1
    # EDIT 2: build the line your engine reads
    board = "".join(".XO"[cell] for cell in position["board"])
    color = "X" if position["color"] == 1 else "O"
    reply = subprocess.run(
        [str(ENGINE)],
        input=f"{board} {color} {think_ms(position)}\n",
        text=True,
        capture_output=True,
        check=True,
        timeout=position["budget_ms"] / 1000 * 0.9,
    )
    # EDIT 3: take the square out of your engine's answer
    return reply.stdout.strip()


position = json.loads(sys.stdin.readline())
legal = position["legal_moves"]
try:
    move = choose_move(position)
except Exception as error:
    # The engine failed: note why in my_adapter.log and play the first legal square.
    with open(Path(__file__).with_name("my_adapter.log"), "a") as log:
        log.write(repr(error) + "\n")
    move = legal[0] if legal else -1
print(json.dumps({"move": move}), flush=True)

เวลาคิด: เกมบอตให้เวลาบอตแต่ละตัว 1 นาทีต่อกระดาน การคิดนานกับตาเดียวจึงทำให้แพ้เพราะหมดเวลาได้เร็ว think_ms ในตัวอย่างนำเวลาที่เหลือ (remaining_ms) มาหารด้วยจำนวนตาที่คุณยังต้องเดิน เพื่อกำหนดเวลาของตานี้ budget_ms ไม่ใช่เวลาที่ควรใช้กับตานี้ แต่เป็นเวลานานที่สุดที่ตัวเชื่อมต่อรอคำตอบ (ค่าเริ่มต้นคือ 10 วินาที) หากคำตอบมาช้ากว่านั้น บอตจะเล่นกระดานนั้นต่อไม่ได้และแพ้กระดานนั้นเพราะหมดเวลา จึงให้ส่ง think_ms ให้เอนจินของคุณ ไม่ใช่ budget_ms

เมื่อมีอะไรผิดพลาด: หากเรียกเอนจินไม่สำเร็จ ไฟล์ตัวอย่างจะเขียนสาเหตุลงใน my_adapter.log และเดินช่องที่ถูกกติกาช่องแรกแทน หากตาเดินดูแปลก ให้เปิดไฟล์นั้นดูก่อน ตัวเชื่อมต่อไม่แสดงข้อความผิดพลาดของอะแดปเตอร์บนหน้าจอ ให้ใช้ print เฉพาะกับคำตอบหนึ่งบรรทัดเท่านั้น และเขียนข้อความดีบักลงไฟล์

ความเร็ว: โปรแกรมเชื่อมต่อจะเปิด my_adapter.py ค้างไว้ในแต่ละเกมและส่งหนึ่งบรรทัดทุกตา ไฟล์ที่ตอบหนึ่งบรรทัดแล้วปิดตัวเหมือนตัวอย่างจะถูกเรียกใหม่ในตาถัดไป เอนจินของคุณจึงเริ่มใหม่ทุกครั้ง ถ้าเอนจินเปิดช้าหรือต้องการใช้งานต่อจากตาก่อนหน้า ให้เปลี่ยน my_adapter.py เป็นวงวน “อ่านหนึ่งบรรทัด ตอบหนึ่งบรรทัด” ซ้ำไป อย่าอ่านอินพุตจนจบ และ flush ทุกครั้งที่ตอบ

ส่วนที่เหลือของหัวข้อนี้เป็นข้อมูลอ้างอิงว่าตัวเชื่อมต่อกับ my_adapter.py รับส่งอะไรกัน หากคุณใช้ไฟล์ตัวอย่างด้านบนตามเดิม ก็ไม่จำเป็นต้องอ่าน

JSON ขาเข้า (ตัวเชื่อมต่อ → อะแดปเตอร์)

นี่คือตัวอย่างข้อมูลที่ตัวเชื่อมต่อส่งมา ไม่ใช่โค้ดสำหรับรัน ไม่ต้องบันทึกเป็นไฟล์ Python ระหว่างเล่น ตัวเชื่อมต่อจะส่งข้อมูลปัจจุบันให้อัตโนมัติทุกตา

ด้านล่างคือตัวอย่างตำแหน่งเริ่มต้นแบบมาตรฐาน 8×8 ในเกมจริง ตัวเชื่อมต่อจะใส่ตำแหน่งปัจจุบันให้ board เรียงช่องจาก a1 ไปทางขวา แล้วต่อด้วยแถวถัดไป โดย 0=ว่าง, 1=ดำ, 2=ขาว color=1 หมายถึงขอตาเดินของฝ่ายดำ legal_moves คือรายการช่องที่คุณเดินได้ remaining_ms คือเวลาที่เหลือของเกม และ budget_ms คือเวลานานที่สุดที่ตัวเชื่อมต่อรอคำตอบของตานี้ ทั้งสองเป็นมิลลิวินาที (1000 = 1 วินาที) ฟิลด์และตัวอย่างของเกมรูปแบบอื่นอยู่ในส่วนเกมรูปแบบอื่นด้านล่าง

{"board":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,2,1,0,0,0,0,0,0,1,2,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"color":1,"legal_moves":[19,26,37,44],"game_mode":"std","board_size":8,"blocked_squares":[],"placed":{"1":0,"2":0},"remaining_ms":60000,"match_id":123,"leg":0,"revision":0,"history":[],"round_no":null,"room_created_at":null,"budget_ms":10000}

JSON ตอบกลับ (อะแดปเตอร์ → ตัวเชื่อมต่อ)

เขียนคำตอบแบบใดแบบหนึ่งด้านล่างเป็น JSON บรรทัดเดียวที่ลงท้ายด้วยการขึ้นบรรทัดใหม่ move คือหมายเลขช่องหรือพิกัด ตัวพิมพ์เล็กหรือใหญ่ก็ได้ บนกระดาน 8×8 d3 คือ (3−1)×8+3 = 19 ต้องเลือกจาก legal_moves ที่ได้รับเสมอ ในการแข่งระหว่างบอต หากไม่มีตาที่ถูกกติกา ให้ส่ง -1 หรือ pass ส่วนเกมกับคน เซิร์ฟเวอร์จัดการการผ่านที่ถูกบังคับเอง เขียนเฉพาะบรรทัดคำตอบลงใน stdout ห้ามมีข้อความอื่น

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

ไม่บังคับ: ใส่ environment ในคำตอบเพื่อรายงานจำนวนเธรด ขนาดแฮชเป็น MB และการคิดล่วงหน้าจริงของเอนจิน (โปรแกรมเชื่อมต่อ v1.4.6 ขึ้นไป) โปรแกรมเชื่อมต่อรับเฉพาะตัวเลขในช่วงที่กำหนดและ true/false แล้วแสดงในข้อมูลบอต ถ้าอะแดปเตอร์ที่ทำเองใส่ eval โปรแกรมเชื่อมต่อจะส่งไปพร้อมตาเดินในการแข่งระหว่างบอต (ตัวอย่าง {"move":19,"eval":1.5}) eval คือค่าประเมินหลังตานั้นเป็นจำนวนหมากจากฝั่งของคุณ สูงสุดเท่าจำนวนช่องของเกม ส่วน --edax, --egaroucid และเอนจิน NBoard จะส่งเองเมื่ออัปเดตเป็น v1.5.3

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

ตัวอย่างคำขอถึงเอนจินแยกตามเกม

ดาวน์โหลด

ดาวน์โหลดตัวอย่าง Python

GitHub: flipsight-othello-bot-connector

OpenAPI 3.1 JSON

README.md

.zip มีคู่มือ โปรแกรมเชื่อมต่อ และเอนจินตัวอย่าง ส่วน .json คือข้อกำหนด API และ .md คือคู่มือ

เขียนการเชื่อมต่อ API เอง

หยุดตัวเชื่อมต่อของบอตฝึกซ้อมก่อน เปิดสตรีมด้วยโทเค็นจากขั้นตอนที่ 6 ใช้หนึ่งการเชื่อมต่อต่อโทเค็น แต่ละบรรทัดมีเหตุการณ์ JSON หนึ่งรายการ

สตรีมเหตุการณ์

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

หลังจาก hello จะได้รับ state ตัวอย่างนี้แสดงเฉพาะฟิลด์ที่เกี่ยวข้องกับบอตของคุณซึ่งมีหมายเลข 2

{
    "type": "state",
    "view": "agent",
    "bot": {
        "id": 2
    },
    "matches": [
        {
            "id": 123,
            "status": "running",
            "bot_a": 1,
            "bot_b": 2,
            "state": {
                "legs": [
                    {
                        "turn": 1,
                        "black_participant": 0,
                        "revision": 1,
                        "status": "active",
                        "legal_moves": [2, 3, 12, 25, 42, 44, 45]
                    },
                    {
                        "turn": 1,
                        "black_participant": 1,
                        "revision": 0,
                        "status": "active",
                        "legal_moves": [2, 3, 12, 25, 42, 44, 45]
                    }
                ]
            }
        }
    ]
}

บนกระดานที่สอง (leg 1) บอตของคุณเล่นสีดำ (1) เมื่อ turn เป็น 1 ให้เลือกตาเดินจาก legal_moves แล้วส่งพร้อมค่า revision ของกระดานนี้ เมื่อต้องการเดินจริง ให้ตั้งค่าโทเค็นในอีกหน้าต่างตามขั้นตอนที่ 6 แล้วใช้ค่าของเกมปัจจุบัน

curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
  -H "Authorization: Bearer $FS_BOT_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"action":"agent_move","match_id":123,"leg":1,"revision":0,"move":2,"eval":1.5}'
Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_move","match_id":123,"leg":1,"revision":0,"move":2,"eval":1.5}'

agent_accept, agent_move

สตรีมเหตุการณ์

เขียนการเชื่อมต่อ API เอง

ชนิดคำอธิบาย
helloเชื่อมต่อแล้ว bot_id คือหมายเลขบอตของคุณ
stateแทนที่รายการเกมที่กำลังเล่นและคำเชิญด้วยรายการที่ได้รับ หากคุณเป็น bot_b คุณสามารถตอบรับคำเชิญสถานะ pending ด้วย agent_accept
matchอัปเดตเกมที่มี id นี้ ตรวจดูทุกกระดานที่กำลังเล่นว่าถึงตาบอตของคุณหรือยัง
pingสัญญาณยืนยันการเชื่อมต่อทุก 10 วินาที ไม่ต้องตอบกลับ
closingบรรทัดสุดท้ายที่เซิร์ฟเวอร์ส่งก่อนปิดสตรีม หาก reason เป็น overflow (มีบรรทัดที่ส่งไม่ออกค้างมากเกินไป) หรือ server_shutdown ให้เชื่อมต่อใหม่แล้วตามสถานะด้วย state ส่วน replaced หมายถึงมีการใช้โทเค็นเดียวกันที่อื่นด้วย อย่าเชื่อมต่อใหม่ทันที ให้รออย่างน้อย 30 วินาที และถ้าเกิดซ้ำให้รอนานขึ้น ใช้โทเค็นแต่ละตัวในที่เดียวเท่านั้น
ออบเจ็กต์การแข่งขัน (matches[])
ฟิลด์ชนิดคำอธิบาย
idintegerID การแข่งขัน (ติดลบสำหรับเกมกับคน)
kindstringhuman สำหรับเกมกับคน
bot_aintegerID บอตของผู้เข้าร่วม 0 (0 สำหรับคน)
bot_bintegerID บอตของผู้เข้าร่วม 1 (0 สำหรับคน)
game_modestringเกม (std, anti, grand, octagon, reversi)
time_limit_secintegerจำนวนวินาทีต่อเกม ต่อสี
statusstringpending, running, finished, aborted, rejected, expired
expires_msintegerกำหนดเวลาตอบรับ (มิลลิวินาที)
rankedbooleanการแข่งขันคิดอันดับหรือไม่
state.statusstringactive, finished หรือ aborted
state.game_modestringเกม (std, anti, grand, octagon, reversi)
state.board_sizeinteger 8 | 10จำนวนช่องต่อด้าน 8 หรือ 10
state.blocked_squaresinteger[]ช่องที่ใช้ไม่ได้ (เฉพาะแปดเหลี่ยม ไม่ได้เรียงลำดับ)
state.legsarrayเกม (2 เกมระหว่างบอต, 1 เกมกับคน)
state.totals[integer, integer]ผลรวมเม็ดของทั้งสองเกมตามผู้เข้าร่วม
state.winnerinteger | nullผู้เข้าร่วมที่ชนะ 0 หรือ 1, null เมื่อเสมอ
state.finish_reasonstring | nulldiscs, timeout, double_timeout, disconnect, no_first_move
ออบเจ็กต์เกม (state.legs[])
ฟิลด์ชนิดคำอธิบาย
boardinteger[64 | 100]64 / 100 ช่อง, 0=ว่าง 1=ดำ 2=ขาว
turnintegerสีที่ต้องเดิน 1 (ดำ) หรือ 2 (ขาว)
legal_movesinteger[]ช่องที่ถูกกติกาของสีที่ต้องเดิน ว่างสำหรับเกมที่จบแล้ว
placed{"1": integer, "2": integer}จำนวนหมากที่แต่ละสีวางแล้ว คีย์ "1" (ดำ) และ "2" (ขาว)
black_participantintegerผู้เข้าร่วมที่เล่นดำในเกมนี้
clocks_ms[number, number]ค่าฐานของเวลาที่เหลือเรียงตามสี (ดำ, ขาว)
turn_started_msintegerเวลาของเซิร์ฟเวอร์เมื่อตาปัจจุบันเริ่ม
revisionintegerเพิ่มขึ้น 1 ทุกครั้งที่เกมนี้เปลี่ยน
statusstringactive, finished, timeout, stopped
historyarrayตาที่เดินแล้ว (color, participant, move, at_ms, eval)
discs[integer, integer]จำนวนเม็ดเรียงตามสี (ดำ, ขาว)
result_discs[integer, integer] (optional)คะแนนตัดสิน [ดำ, ขาว] ของเกมที่แพ้เพราะหมดเวลา (ไม่บังคับ) หากมีค่านี้ ให้ใช้รวมแทนจำนวนหมาก (discs) คะแนนของฝ่ายที่หมดเวลาและคู่แข่ง: std และ reversi 0 ต่อ 64, grand 0 ต่อ 100, octagon 0 ต่อ 88, anti 64 ต่อ 0 อีกเกมหนึ่งเล่นต่อไป และเมื่อทั้งสองเกมจบ ผลรวมจะตัดสินผู้ชนะ บันทึกที่จบไปแล้วก่อนหน้านี้จะไม่ถูกคำนวณใหม่

เมื่อเกมจบ เหตุการณ์ match สุดท้ายจะมี record ซึ่งเป็นบันทึกเกมมาด้วย เก็บไว้ตามที่ได้รับเพื่อให้ได้เกมครบทั้งเกม บันทึกเกม

ซิงค์สถานะ

หากการเชื่อมต่อหลุดหรือไม่ได้รับเหตุการณ์นาน 15 วินาที ให้เชื่อมต่อใหม่โดยเพิ่มช่วงรอจาก 1 ถึง 30 วินาที ข้ามสถานะที่เก่ากว่า เมื่อเล่นกับคนให้เทียบ room_created_at ตามด้วย round_no และ revision หากไม่ได้รับคำตอบหลังส่งตาเดิน ให้ส่งซ้ำเฉพาะเมื่อยังเป็นตาของคุณและ revision ของกระดานยังเท่าเดิม

ส่งข้อมูลเอนจินด้วย agent_environment เมื่อเริ่มทำงานและเมื่อข้อมูลเปลี่ยน สำหรับการจับคู่อัตโนมัติ v2 อนุญาตให้เชื่อมต่อสตรีมไม่เกิน 10 ครั้งและไม่เรียก agent_poll เลยในช่วง 10 นาทีล่าสุดที่ออนไลน์

การยืนยันตัวตน

ใช้ HTTPS, JSON POST และ Authorization: Bearer โทเคนเป็นของบอตเดียว อย่าใส่ใน URL โค้ดสาธารณะ หรือบันทึกระบบ

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

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

ตัวเลือกของตัวเชื่อมต่อ

ตัวเลือกของ tools/bot_match_client.py ต้องระบุ --engine หรือ --nboard / --edax / --egaroucid อย่างใดอย่างหนึ่งเท่านั้น โทเคนไม่เคยเป็นตัวเลือก จะอ่านจากตัวแปรสภาพแวดล้อม FS_BOT_TOKEN เท่านั้น รหัสออก: 0 หยุดตามปกติ, 2 โทเคนถูกปฏิเสธ, 3 ถึง --max-runtime

พารามิเตอร์คำอธิบาย
--engine "COMMAND"เปิดคำสั่งนี้ครั้งเดียวต่อเกมแล้วเปิดค้างไว้ และแลก JSON หนึ่งบรรทัดทุกตาโดยไม่ปิดอินพุต เอนจินที่ตอบหนึ่งบรรทัดแล้วปิดตัวจะถูกเปิดใหม่ในตาถัดไป
--nboard "COMMAND"เปิดเอนจิน NBoard ค้างไว้หนึ่งตัวต่อเกม รวมสองตัว เฉพาะเกมมาตรฐาน (std)
--edax PATHEdax เชื่อมต่อได้โดยระบุเพียงพาธไฟล์โปรแกรมด้วย --edax ตามด้านล่าง ไม่ต้องสร้างอะแดปเตอร์แยก ตัวเชื่อมต่อจะเปิด Edax ผ่าน xboard และส่งเวลาที่เหลือของทั้งสองฝ่ายก่อนทุกตา Edax กำหนดเวลาคิดเองตามนาฬิกาของตัวเอง (ตัวเชื่อมต่อ v1.4.8 ขึ้นไป) ระหว่างเกม Edax เก็บประวัติเกมและตารางแฮชไว้ และเมื่อใช้ --engine-ponder on จะค้นหาในเวลาของคู่แข่งด้วย --edax-protocol nboard ใช้การเชื่อมต่อแบบ NBoard แบบเดิม
--edax-eval PATHพาธ eval.dat ของ Edax ถ้าไม่ระบุจะหา data/eval.dat ในโฟลเดอร์โปรแกรมหรือโฟลเดอร์แม่
--edax-protocol xboard|nboardวิธีเชื่อมต่อของ --edax ค่าเริ่มต้น xboard ให้ Edax จัดการนาฬิกาเองและคิดล่วงหน้าได้ (v1.4.8 ขึ้นไป) ส่วน nboard คือการเชื่อมต่อที่ใช้ถึง v1.4.7 โดยตัวเชื่อมต่อกำหนดเวลาแต่ละตาและ Edax ไม่คิดล่วงหน้า
--egaroucid PATHเตรียม Egaroucid for Console เลือกไฟล์โปรแกรมคอนโซลและเก็บโฟลเดอร์ resources ไว้ที่เดิม บน macOS และ Linux ให้ใช้โปรแกรมที่สร้างตามคู่มือทางการ โปรแกรมเชื่อมต่อส่งกระดานและเวลาที่เหลือด้วย setboard, settime และ go จึงไม่ต้องเขียนอะแดปเตอร์
--egaroucid-level Nใช้คู่กับ --egaroucid ค่า 1 ถึง 60 จะเริ่ม Egaroucid ที่ระดับนั้น (-level N) และไม่ส่งเวลาที่เหลือ (settime) ส่วน 0 หรือไม่กำหนดจะใช้โหมดเวลาที่เดินตามนาฬิกาของเกม โหมดระดับไม่มีคำสั่งหยุดการค้นหากลางคัน ถ้าตาใดเกินเพดาน --max-think-seconds ตัวเชื่อมต่อจะหยุดเอนจินและเดินตาที่ถูกกติกาแทน 1 ตา ควรเลือกระดับที่เสร็จทันภายในนาฬิกาของเกมอย่างสบาย
--nboard-depth Nส่ง set depth N ไปยังเอนจิน NBoard ค่า 0 ถึง 60 โดย 0 คือใช้ค่าเริ่มต้นของเอนจิน เมื่อใช้กับ --edax ค่านี้คือระดับของ Edax (20 คือ L20) ถ้าไม่กำหนด ระดับคือ 60 Edax จะเดินตาที่ดีที่สุดที่หาได้เมื่อถึงระดับนั้นหรือเมื่อเวลาของตานั้นหมด แล้วแต่อย่างใดถึงก่อน เมื่อใช้ --edax ค่านี้จะส่งผ่าน xboard เป็น sd N
--max-think-seconds Sจำนวนวินาทีสูงสุดที่รอเอนจินต่อตา ค่าเริ่มต้น 10 สูงสุด 300 ไม่เกินเวลาที่เหลือลบ 0.75 วินาที นี่คือเพดานความปลอดภัยของตัวเชื่อมต่อ เซิร์ฟเวอร์ไม่มีการจำกัดเวลาต่อตา ตั้งเป็น 0 เพื่อยกเลิกเพดานต่อตาและใช้เวลาเกมที่เหลือ นาฬิกาของเกมกำหนดโดยเว็บไซต์ และตัวเชื่อมต่อเปลี่ยนไม่ได้ เกมระหว่างบอตและเกมบอตอัตโนมัติให้แต่ละสี 60 วินาทีต่อกระดาน ส่วนคนที่ท้าบอตของคุณโดยตรงจะเลือกเวลาเอง เมื่อใช้ --edax Edax จะกำหนดเวลาต่อตาเองตามนาฬิกาของตัวเองภายในเพดานนี้ หากถึงเพดาน ตัวเชื่อมต่อจะให้ Edax เดินตาที่ดีที่สุดที่หาได้ทันที
--engine-name NAMEชื่อเอนจินที่แสดงในข้อมูลบอต (ไม่เกิน 120 ตัวอักษร) อย่าใส่คำสั่งหรือพาธ
--engine-threads Nจำนวนเธรดที่เอนจินใช้ต่อเกม แสดงในบันทึกผู้ใช้ เมื่อใช้ --edax หรือ --egaroucid เอนจินจะทำงานด้วยค่านี้ (ค่าเริ่มต้นเป็น 4 ถ้าเครื่องมี CPU เชิงตรรกะมากกว่า 4 ตัว ไม่เช่นนั้นเป็น 1) เมื่อใช้ --engine จะส่งในทุกคำขอเป็น engine_threads ใช้ไม่เกิน 4 เธรดต่อเอนจิน และรวมไม่เกิน 8 เธรดต่อแมตช์บอตที่เล่นสองเกมพร้อมกัน เมื่อใช้ --engine/--nboard หากไม่ระบุจะมีข้อความให้ป้อนค่า แต่การรันเบื้องหลังหรือแบบอัตโนมัติต้องระบุตัวเลือกนี้
--engine-hash-mb MBขนาดตารางแฮชต่อเอนจิน (MB) เมื่อใช้ --edax หรือ --egaroucid จะตั้งตารางเป็นขนาดกำลังของสองที่ใหญ่ที่สุดซึ่งไม่เกินค่านี้ (Edax -h, Egaroucid -hash) และรายงานขนาดนั้น ถ้าไม่ระบุ Edax ใช้ edax.ini และ Egaroucid ใช้ 32 MB เอนจินอื่นจะรายงานค่าอย่างเดียวโดยไม่เปลี่ยนการตั้งค่า เอนจินแต่ละตัวมีตารางของตัวเอง เกมบอตที่เล่นสองกระดานพร้อมกันจึงใช้เป็นสองเท่า
--engine-ponder on|offคิดล่วงหน้า (ค้นหาระหว่างเวลาของคู่แข่ง) เมื่อใช้ --egaroucid ค่า on จะเปิด Egaroucid ด้วย -ponder และรายงานว่าเปิด โดยใช้ CPU ในตาของคู่แข่งด้วย เมื่อใช้ --edax (ตัวเชื่อมต่อ v1.4.8 ขึ้นไป) ค่า on จะให้ Edax คิดล่วงหน้าผ่าน xboard (hard) และรายงานว่าเปิด ส่วน --edax-protocol nboard นั้น Edax ไม่คิดล่วงหน้าและไม่รับ on เอนจินอื่นจะรายงานการตั้งค่าจริงเท่านั้น
--cpu-name NAMEชื่อ CPU ที่จะรายงาน (ไม่เกิน 120 ตัวอักษร) หากไม่ระบุจะตรวจหาให้อัตโนมัติ
--once-match IDจัดการเฉพาะการแข่งขันนี้ และออกเมื่อการแข่งขันจบ (finished, aborted, expired, rejected) ใช้กับ ID ติดลบของเกมกับคนได้ด้วย สำหรับการทดสอบ ให้ใช้คู่กับ --max-runtime
--max-runtime Sปิดเอนจินและออกหลังผ่านไปตามจำนวนวินาทีนี้ (รหัสออก 3)
--save-games DIRเก็บทุกเกมที่จบหลังเปิดตัวเลือกนี้ไว้ใน DIR/games-YYYY-MM.ndjson บรรทัดละหนึ่งบันทึกเกม (ปิดไว้โดยค่าเริ่มต้น) เกมที่จบระหว่างที่ตัวเชื่อมต่อหยุดทำงานหรือสตรีมขาด จะถูกเติมด้วย agent_games เมื่อเชื่อมต่อใหม่ โดยเริ่มจากเกมล่าสุดที่เก็บไว้ หนึ่งเกมใช้ประมาณ 4 KB (บน 10×10 ประมาณ 6 KB) ถ้าวันละ 1,400 เกมจะเป็นประมาณวันละ 6 MB และเดือนละ 180 MB ไฟล์ของเดือนเก่าที่ไม่ใช้แล้วให้ลบเอง
--timing-log PATHเพิ่มหนึ่งบรรทัดต่อตาเดินในไฟล์ว่าเวลาไปอยู่ที่ใด (รับตาเดิน รอช่องค้นหาว่าง เอนจิน ส่งตาเดิน) ปิดไว้โดยค่าเริ่มต้น และไม่ส่งอะไรเพิ่มไปยังเซิร์ฟเวอร์
--api URL, --stream-url URLที่อยู่ของ API และสตรีม ปกติให้ใช้ค่าเริ่มต้น รับเฉพาะ HTTPS และเนื่องจากโทเคนถูกส่งไปด้วย สตรีมต้องอยู่บนโฮสต์ของ API

เกมรูปแบบอื่น

บอตจะได้รับเฉพาะเกมที่เลือกไว้ใน เกมที่รองรับ ค่า game_mode ในคำขอถึงเอนจินและสถานะการแข่งขันบอกว่าเป็นเกมอะไร เซิร์ฟเวอร์คำนวณขนาดกระดาน ช่องที่ถูกปิด และช่องที่ถูกกติกาให้ เอนจินจึงแค่เลือกจาก legal_moves ที่ได้รับ อย่าสร้างตาเดินของ 10×10 หรือรีเวอร์ซีคลาสสิกด้วยการสร้างตาเดินแบบมาตรฐาน 8×8

เกมgame_modeกระดาน
มาตรฐานstd8×8
Antianti8×8
Grand (10x10)grand10×10
Octagonoctagon10×10 (88)
รีเวอร์ซีคลาสสิกreversi8×8

กติการ่วม: ฝ่ายดำ (1) เดินก่อน ทั้งสองเกมเริ่มจากตำแหน่งเดียวกันโดยสลับสี และเล่นพร้อมกัน ในการแข่งระหว่างบอต เมื่อคุณไม่มีตาที่ถูกกติกา legal_moves จะมาเป็นอาร์เรย์ว่าง และบอตต้องส่ง move=-1 (ผ่าน) เอง เซิร์ฟเวอร์จะไม่ผ่านแทนคุณ และเวลาของคุณยังเดินต่อไป การผ่านทั้งที่มีตาที่ถูกกติกาถือว่าผิดกติกา เกมจะจบเมื่อไม่มีสีใดเดินได้ สำหรับแมตช์สองเกมที่เริ่มใหม่ เมื่อแต่ละเกมจบตามปกติ จะนับช่องว่างให้สีที่มีหมากมากกว่า แล้วรวมคะแนนทั้งสองเกม ในแอนติฝ่ายที่มีคะแนนรวมหลังปรับน้อยกว่าจะชนะ หากหมากเท่ากันจะไม่เพิ่มช่องว่าง คะแนนรวมเท่ากันถือว่าเสมอ เกมบอตทุกประเภทเริ่มจากตำแหน่งสุ่มที่มีหมาก 12 ตัว ทุกประเภทเกมให้เวลาบอตแต่ละตัว 1 นาทีต่อกระดาน

Anti: การวางและการพลิกหมากเหมือนโอเทลโลมาตรฐาน ฝ่ายที่มีหมากรวมทั้งสองเกมน้อยกว่าชนะ

10x10: กติกามาตรฐานบนกระดาน 10×10 (100 ช่อง) ตำแหน่งเริ่มต้นคือสี่ช่องตรงกลาง การแข่งระหว่างบอตจะเดินสุ่มเพิ่มอีก 8 ตา และเริ่มที่ 12 หมาก

แปดเหลี่ยม: กระดานและการวางเริ่มต้นเหมือน 10x10 แต่ใช้สามช่องในแต่ละมุมไม่ได้ รวม 12 ช่อง (เล่นได้ 88 ช่อง) ช่องที่ถูกปิดจะมาเป็นหมายเลขช่องใน blocked_squares และเป็น 0 ซึ่งเป็นค่าเดียวกับช่องว่างใน board อาร์เรย์นี้ไม่ได้เรียงตามหมายเลข วางหมากบนช่องที่ถูกปิดไม่ได้ และแนวหมากจะขาดที่ช่องนั้น

รีเวอร์ซีคลาสสิก: ตามกติกาจะเริ่มจากกระดานว่าง ขณะที่ยังมีช่องว่างในสี่ช่องตรงกลาง (27, 28, 35, 36) ให้วางได้เฉพาะที่นั่นและไม่มีการพลิกหมาก เมื่อทั้งสี่ช่องเต็มแล้วจึงใช้กติกามาตรฐาน แต่ละสีวางหมากได้ไม่เกิน 32 หมาก รวมสี่ตาแรกด้วย placed คือจำนวนหมากที่แต่ละสีวางไปแล้ว คีย์เป็นสตริง "1" (ดำ) และ "2" (ขาว) การแข่งระหว่างบอตจะเริ่มหลังจากเซิร์ฟเวอร์วางหมากแบบสุ่มไปแล้ว 12 ตา รวมสี่ตาตรงกลางด้วย ดังนั้นในคำขอแรก placed ของสองสีรวมกันได้ 12 (ปกติคือ {"1":6,"2":6}) สีที่วางครบ 32 หมากแล้วจะได้ legal_moves ว่าง และส่ง -1 ทุกครั้งที่ถึงตา

ตัวอย่างคำขอถึงเอนจินแยกตามเกม

ตัวอย่างคำขอแรกของฝ่ายดำที่ตัวเชื่อมต่อส่งให้เอนจินแบบ --engine สร้างด้วยโค้ดกติกา เกมจริงทุกประเภทเริ่มจากตำแหน่งสุ่มที่มี 12 หมาก ดังนั้น board และ legal_moves จะต่างกันในทุกเกม เพื่อให้ตัวอย่างเหล่านี้คงที่ จึงเลือกตาเปิดเกมไว้ใกล้กลางกระดาน ในเกมจริง match_id และค่าเวลาก็ต่างออกไปด้วย

Anti (anti)

JSON ขาเข้า (ตัวเชื่อมต่อ → อะแดปเตอร์)

{
    "board": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 2, 2, 0, 0, 0, 0, 0, 1, 2, 2, 1, 0, 0, 0, 0, 2, 2, 2, 2, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    "color": 1,
    "legal_moves": [2, 3, 12, 25, 42, 44, 45],
    "game_mode": "anti",
    "board_size": 8,
    "blocked_squares": [],
    "placed": {
        "1": 4,
        "2": 4
    },
    "remaining_ms": 60000,
    "match_id": 123,
    "leg": 0,
    "revision": 0,
    "history": [],
    "round_no": null,
    "room_created_at": null,
    "budget_ms": 10000
}

JSON ตอบกลับ (อะแดปเตอร์ → ตัวเชื่อมต่อ)

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

JSON ขาเข้า (ตัวเชื่อมต่อ → อะแดปเตอร์)

{
    "board": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 2, 0, 0, 0, 0, 0, 0, 0, 1, 2, 2, 1, 0, 0, 0, 0, 0, 0, 2, 2, 2, 2, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    "color": 1,
    "legal_moves": [13, 14, 25, 42, 63, 65, 66],
    "game_mode": "grand",
    "board_size": 10,
    "blocked_squares": [],
    "placed": {
        "1": 4,
        "2": 4
    },
    "remaining_ms": 60000,
    "match_id": 123,
    "leg": 0,
    "revision": 0,
    "history": [],
    "round_no": null,
    "room_created_at": null,
    "budget_ms": 10000
}

JSON ตอบกลับ (อะแดปเตอร์ → ตัวเชื่อมต่อ)

{"move":13}
Octagon (octagon)

JSON ขาเข้า (ตัวเชื่อมต่อ → อะแดปเตอร์)

{
    "board": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 2, 0, 0, 0, 0, 0, 0, 0, 1, 2, 2, 1, 0, 0, 0, 0, 0, 0, 2, 2, 2, 2, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    "color": 1,
    "legal_moves": [13, 14, 25, 42, 63, 65, 66],
    "game_mode": "octagon",
    "board_size": 10,
    "blocked_squares": [0, 1, 10, 8, 9, 19, 80, 90, 91, 89, 98, 99],
    "placed": {
        "1": 4,
        "2": 4
    },
    "remaining_ms": 60000,
    "match_id": 123,
    "leg": 0,
    "revision": 0,
    "history": [],
    "round_no": null,
    "room_created_at": null,
    "budget_ms": 10000
}

JSON ตอบกลับ (อะแดปเตอร์ → ตัวเชื่อมต่อ)

{"move":13}
รีเวอร์ซีคลาสสิก (reversi)

JSON ขาเข้า (ตัวเชื่อมต่อ → อะแดปเตอร์)

{
    "board": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 2, 2, 1, 1, 0, 0, 0, 0, 2, 2, 1, 1, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    "color": 1,
    "legal_moves": [18, 25, 33, 41, 42, 50, 51],
    "game_mode": "reversi",
    "board_size": 8,
    "blocked_squares": [],
    "placed": {
        "1": 6,
        "2": 6
    },
    "remaining_ms": 60000,
    "match_id": 123,
    "leg": 0,
    "revision": 0,
    "history": [],
    "round_no": null,
    "room_created_at": null,
    "budget_ms": 10000
}

JSON ตอบกลับ (อะแดปเตอร์ → ตัวเชื่อมต่อ)

{"move":18}

ฟิลด์ในคำขอถึงเอนจิน

ฟิลด์ชนิดคำอธิบาย
game_modestringค่าใดค่าหนึ่งจาก std, anti, grand, octagon, reversi XOT ในเกมกับคนจะมาเป็น std
board_sizeinteger 8 | 108 หรือ 10 สำหรับ grand และ octagon
boardinteger[board_size²]อาร์เรย์ความยาว board_size² อ่านจาก a1 ไปทางขวา แล้วต่อด้วยแถวถัดไป 0=ว่าง (รวมช่องที่ถูกปิดของแปดเหลี่ยม), 1=ดำ, 2=ขาว
blocked_squaresinteger[]ช่องที่ใช้ไม่ได้ของแปดเหลี่ยม ในเกมอื่นเป็นอาร์เรย์ว่าง
placed{"1": integer, "2": integer}จำนวนหมากที่แต่ละสีวางไปแล้ว รวมตาสุ่มตอนเริ่มเกม คีย์เป็นสตริง "1" และ "2" ใช้กับขีดจำกัด 32 หมากของรีเวอร์ซีคลาสสิก
legal_movesinteger[]ช่องที่คุณเดินได้ตอนนี้ หากว่าง ให้ตอบ move=-1
colorinteger 1 | 2สีที่ต้องเดิน 1=ดำ, 2=ขาว
budget_msintegerเวลาที่ให้สำหรับตานี้เป็นมิลลิวินาที: ค่าที่น้อยกว่าระหว่าง --max-think-seconds กับเวลาที่เหลือลบ 0.75 วินาที ตัวเชื่อมต่อจะหยุดเอนจินเมื่อเกินเวลานี้
remaining_msintegerเวลาที่เหลือของสีคุณในเกมนี้เป็นมิลลิวินาที หลังหักเวลาที่ใช้ไปแล้วในตานี้
match_idinteger ≠ 0ID การแข่งขัน เป็นค่าติดลบ (-หมายเลขห้อง) สำหรับเกมกับคน
leginteger 0 | 1หมายเลขเกม 0 หรือ 1 เป็น 0 เสมอสำหรับเกมกับคน
revisionintegerหมายเลขสถานะของเกมนี้ ส่งไปกับ agent_move โดยไม่เปลี่ยนค่า
historyarrayตาเดินที่เล่นไปแล้วในเกมนี้ ให้ตัดสินใจจาก board
round_nointeger | nullหมายเลขรอบของเกมกับคน เป็น null สำหรับการแข่งระหว่างบอต
room_created_atstring | nullเวลาที่สร้างห้องเกมกับคน เป็น null สำหรับการแข่งระหว่างบอต
engine_threadsinteger (optional)มีเฉพาะเมื่อเปิดโปรแกรมเชื่อมต่อด้วย --engine-threads คือจำนวนเธรดที่เอนจินใช้ได้ในเกมนี้ ให้ปรับการค้นหาตามค่านี้

ท้าบอตอื่นในเกมรูปแบบอื่น

เพิ่ม game_mode ใน agent_challenge ค่าเริ่มต้นคือ std บอตทั้งสองต้องมีเกมนี้ใน supported_games ดูเกมของคู่แข่งได้ที่หน้าบอต หากบอตฝ่ายใดไม่มีเกมนี้ คำตอบจะเป็น HTTP 409 พร้อมข้อผิดพลาดด้านล่าง

{"action":"agent_challenge","target_id":2,"game_mode":"anti"}
{"action":"agent_challenge","target_name":"Opponent","game_mode":"grand"}
HTTP 409
{"ok":false,"error":"unsupported game mode","server_now_ms":1800000000000}

การเปลี่ยน supported_games

แบบฟอร์มลงทะเบียนเลือก มาตรฐาน ไว้ตั้งแต่ต้น และบอตเก่าที่ไม่มีรายการบันทึกไว้จะรองรับ std เปลี่ยนรายการได้เฉพาะใน จัดการ บนหน้าเว็บบอตเท่านั้น เปลี่ยนด้วยโทเคนบอต (API) ไม่ได้ การเปลี่ยนจะถูกปฏิเสธขณะมีการแข่งขันกำลังเล่นหรือรอการรับ บันทึกรายการว่างไม่ได้

คนกับบอตที่ลงทะเบียน

ผู้เล่นท้าบอตของคุณได้ในทุกเกมที่บอตลงทะเบียนไว้ หากรองรับเกมมาตรฐาน อาจมีทั้ง STD และ XOT เข้ามา XOT มาพร้อม game_mode std และเริ่มจากกระดานที่เดินไปแล้ว 8 ตา (รวมอยู่ใน history) ผู้ท้าเป็นคนเลือกเวลา และเกมไม่คิดเรตติ้ง เกมกับคนมีเกมเดียว (leg 0) และ match_id ติดลบ เซิร์ฟเวอร์จัดการการผ่านเมื่อเดินไม่ได้ จึงไม่ต้องส่ง -1 บอตที่ลงทะเบียนและออนไลน์พร้อมเปิดจับคู่อัตโนมัติจะเข้าร่วมจับคู่ด่วน STD/XOT ที่รองรับด้วย เกมจับคู่ด่วนของสมาชิกคิดเรตติ้ง ส่วนของผู้เยี่ยมชมไม่คิดเรตติ้ง

ตาผิดกติกาและเวลา

ตาที่ผิดกติกาหรือ revision ที่ล้าสมัยจะถูกปฏิเสธด้วย HTTP 409 (illegal_move, stale_revision, not_your_turn) และกระดานไม่เปลี่ยน ระหว่างนั้นเวลายังเดินต่อ ตัวเชื่อมต่อจะส่งตาเดิมพร้อม revision เดิมซ้ำ ดังนั้นหากไม่แก้เอนจิน เกมนั้นจะแพ้เพราะหมดเวลาในที่สุด เซิร์ฟเวอร์ไม่มีการจำกัดเวลาต่อตา ตรวจเฉพาะเวลาที่เหลือของแต่ละสี 10 วินาทีคือค่าเริ่มต้นของ --max-think-seconds ของตัวเชื่อมต่อ

กติกาการแข่งขัน

เกมบอตทุกประเภทเริ่มจากตำแหน่งสุ่มที่มีหมาก 12 ตัว แข่งสองเกมพร้อมกันโดยสลับสี ตัดสินจากจำนวนหมากรวม ส่วน Anti ฝ่ายที่มีหมากน้อยกว่าชนะ

ทุกประเภทเกมให้เวลาบอตแต่ละตัว 1 นาทีต่อกระดาน

หากบอตไม่เดินตาแรกภายใน 30 วินาทีหลังเริ่ม การแข่งขันจะถูกยกเลิกและไม่คิดอันดับ หากระหว่างการแข่งขันบอตฝ่ายหนึ่งขาดการเชื่อมต่อนานกว่า 30 วินาทีขณะที่อีกฝ่ายยังเชื่อมต่ออยู่ บอตที่เชื่อมต่ออยู่จะชนะ (finish_reason: disconnect) และผลจะถูกคิดอันดับ

ในเกมทุกประเภท เซิร์ฟเวอร์เป็นผู้คำนวณตาเดินของบอต FlipSight รับคำท้าทั้งจากเว็บและผ่าน API (agent_challenge) และเซิร์ฟเวอร์จะเริ่มการแข่งทันที จึงไม่ต้องเปิดห้องเกมไว้ หากการคำนวณของเซิร์ฟเวอร์หยุดนานกว่า 30 วินาที การแข่งนั้นจะเป็นโมฆะ (finish_reason: technical) และไม่นำไปคิดเรตติ้ง เกมรูปแบบอื่นคำนวณหนัก จึงแข่งกับบอต FlipSight ได้พร้อมกันสูงสุด 2 การแข่ง ถ้าเต็มจะได้ HTTP 409 พร้อม site bot variant matches are full โปรดลองใหม่ในภายหลัง

การจับคู่อัตโนมัติจับคู่บอตที่เรตติงต่างกันไม่เกิน 500 คะแนนในประเภทที่ทั้งคู่เลือก โปรแกรมเชื่อมต่อมีเวลา 120 วินาทีในการตอบรับ ผลจะนับในเรตติง เลือกประเภทหรือปิดการจับคู่อัตโนมัติได้ใน จัดการ บอตที่เปิดด้วยเอนจินฝึกซ้อม (environment.practice เป็น true) จะไม่ถูกจับคู่บอตแข่งอัตโนมัติ และเกมระหว่างบอตในช่วงนั้นจะไม่นำไปคิดเรตติ้ง

คำท้าโดยตรงจากคนจะเล่นหนึ่งเกมในห้องปกติ โดยเลือกเกมและเวลาที่รองรับ เซิร์ฟเวอร์กำหนดให้คำท้าโดยตรงไม่คิดเรตติ้งเสมอ บอตที่ลงทะเบียนและออนไลน์พร้อมเปิดจับคู่อัตโนมัติจะเข้าร่วมจับคู่ด่วน STD/XOT ที่รองรับด้วย เกมจับคู่ด่วนของสมาชิกคิดเรตติ้ง ส่วนของผู้เยี่ยมชมไม่คิดเรตติ้ง บอตที่ลงทะเบียนจะรับเกมได้ไม่เกินจำนวนเกมพร้อมกันที่ตั้งไว้ในการจัดการบอต (ค่าเริ่มต้น 2) เกมกับคน 1 เกม และการแข่งระหว่างบอต 1 ครั้ง (2 กระดาน) นับเป็น 1 อย่างละครั้ง

ขั้นตอนการแข่งขัน

pending → running → finished / aborted
pending → rejected / expired
kind=human: id=-room_id, legs[0], round_no, room_created_at
agent_move: move=19 / "d3" / "D3" (8×8)
10×10: "j10" = "J0" = 99
pass: -1 / "pass" / "PA" / "PS" / "--" (paired games only)
index=row*board_size+column (0-based)

เกมบอตทุกประเภทเริ่มจากตำแหน่งสุ่มที่มีหมาก 12 ตัว แข่งสองเกมพร้อมกันโดยสลับสี ตัดสินจากจำนวนหมากรวม ส่วน Anti ฝ่ายที่มีหมากน้อยกว่าชนะ

หมายเลขผู้เข้าร่วมของคุณคือ 0 หากคุณเป็น bot_a และ 1 หากเป็น bot_b ผู้เข้าร่วม 0 เล่นดำ (1) ใน legs[0] และขาว (2) ใน legs[1] ส่วนผู้เข้าร่วม 1 กลับกัน ถึงตาคุณเมื่อ leg.status เป็น active และ leg.turn เท่ากับสีของคุณ อาจถึงตาคุณในทั้งสองเกมพร้อมกันได้

หากไม่มีตาที่ถูกกติกา คุณต้องส่ง move -1 (ผ่าน) เอง เซิร์ฟเวอร์จะไม่ผ่านแทนคุณ ในเกมที่เล่นกับคน เซิร์ฟเวอร์จัดการการผ่านเหมือนห้องเกมปกติ

ในตาของคุณ เวลาที่เหลือ = clocks_ms[สีของคุณ - 1] - (server_now_ms - turn_started_ms) โดย clocks_ms เรียงตามสี (ดำ, ขาว) ส่วน totals และ winner เรียงตามผู้เข้าร่วม (winner เป็น 0 หรือ 1 และเป็น null เมื่อเสมอ)

หมายเลขช่อง

หมายเลขช่อง = แถว × 8 + คอลัมน์ ดังนั้น a1=0, h1=7, a2=8 และ h8=63 เช่น 19 คือ d3 และ 37 คือ f5 อาร์เรย์ board ใช้ลำดับเดียวกัน โดย 0=ว่าง, 1=ดำ, 2=ขาว

    a  b  c  d  e  f  g  h
1   0  1  2  3  4  5  6  7
2   8  9 10 11 12 13 14 15
3  16 17 18 19 20 21 22 23
4  24 25 26 27 28 29 30 31
5  32 33 34 35 36 37 38 39
6  40 41 42 43 44 45 46 47
7  48 49 50 51 52 53 54 55
8  56 57 58 59 60 61 62 63

บน 10×10 (grand, octagon) ช่อง = แถว × 10 + คอลัมน์ คอลัมน์คือ a ถึง j และแถวที่สิบเขียนเป็น 10 หรือ 0 ในพิกัด a1=0, j1=9, a2=10, j10=99 (เหมือน j0) พิกัดเดียวกันมีหมายเลขต่างกันตามขนาดกระดาน: d3 คือ 19 บน 8×8 และ 23 บน 10×10

     a  b  c  d  e  f  g  h  i  j
  1   0  1  2  3  4  5  6  7  8  9
  2  10 11 12 13 14 15 16 17 18 19
  3  20 21 22 23 24 25 26 27 28 29
  4  30 31 32 33 34 35 36 37 38 39
  5  40 41 42 43 44 45 46 47 48 49
  6  50 51 52 53 54 55 56 57 58 59
  7  60 61 62 63 64 65 66 67 68 69
  8  70 71 72 73 74 75 76 77 78 79
  9  80 81 82 83 84 85 86 87 88 89
 10  90 91 92 93 94 95 96 97 98 99

Octagon (octagon)

     a  b  c  d  e  f  g  h  i  j
  1  ## ##  2  3  4  5  6  7 ## ##
  2  ## 11 12 13 14 15 16 17 18 ##
  3  20 21 22 23 24 25 26 27 28 29
  4  30 31 32 33 34 35 36 37 38 39
  5  40 41 42 43 44 45 46 47 48 49
  6  50 51 52 53 54 55 56 57 58 59
  7  60 61 62 63 64 65 66 67 68 69
  8  70 71 72 73 74 75 76 77 78 79
  9  ## 81 82 83 84 85 86 87 88 ##
 10  ## ## 92 93 94 95 96 97 ## ##

ตัวเชื่อมต่อเอนจิน

โปรแกรมเชื่อมต่อบอต FlipSight (Python 3.9 ขึ้นไป ใช้เฉพาะไลบรารีมาตรฐาน) ทำงานบน Windows, macOS และ Linux และเชื่อมต่อเอนจินได้สองแบบ --engine จะเปิดเอนจินครั้งเดียวต่อเกมแล้วเปิดค้างไว้ ส่ง JSON หนึ่งบรรทัดทุกตา และอ่านคำตอบ {"move": ช่อง} หนึ่งบรรทัด เอนจินที่ตอบหนึ่งบรรทัดแล้วปิดตัวยังใช้ได้เพราะจะถูกเปิดใหม่ในตาถัดไป แต่เอนจินที่อ่านอินพุตจนจบ (sys.stdin.read() เป็นต้น) จะไม่ตอบเลย จึงต้องอ่านทีละบรรทัด legal_moves ในคำขอคือรายการช่องที่เดินได้ ถ้าว่างให้ตอบ -1 ส่วน --nboard จะเปิดเอนจินโปรโตคอล NBoard ค้างไว้เกมละหนึ่งตัว และกำหนดความลึกด้วย --nboard-depth

JSON ขาเข้า (ตัวเชื่อมต่อ → อะแดปเตอร์)

ตัวเลือกของตัวเชื่อมต่อ

คำสั่ง API

ตัวอย่างคำตอบแสดงรูปแบบ ปุ่มคัดลอกคัดลอกเฉพาะคำขอและไม่เรียก API

POST agent_environment

รายงานสภาพแวดล้อม

แจ้ง CPU, OS, ชื่อเอนจิน, จำนวนเธรด และสถานะฝึกซ้อม (practice) ของเครื่องที่รันโปรแกรมเชื่อมต่อ ส่งตอนเริ่มและเมื่อค่าเปลี่ยน คำตอบจะมีข้อมูลบอทของคุณ

พารามิเตอร์ชนิดจำเป็นคำอธิบาย
actionstring "agent_environment"จำเป็นชื่อแอ็กชันที่จะเรียก
environmentobjectจำเป็นCPU, OS และชื่อเอนจินของเครื่องที่รันโปรแกรมเชื่อมต่อ (แต่ละค่าไม่เกิน 120 อักขระ ไม่บังคับ) และ practice (true หรือ false ไม่บังคับ) ถ้า practice เป็น true แปลว่าบอตกำลังฝึกซ้อม จะไม่ถูกจับคู่บอตแข่งอัตโนมัติ และเกมระหว่างบอตที่ท้าหรือรับในช่วงนั้นจะไม่นำไปคิดเรตติ้ง โปรแกรมเชื่อมต่อจะส่งค่านี้เองเมื่อเปิดด้วยเอนจินฝึกซ้อม เซิร์ฟเวอร์จำค่าล่าสุดไว้ เมื่อเลิกฝึกซ้อมให้ส่งโดยไม่มี practice หรือส่งเป็น false hash_mb (MB): ต่อเอนจิน หากตัวเชื่อมต่อไม่ส่งค่า ให้กรอกเองได้ ponder (true / false / null): ใช้แสดงข้อมูลเท่านั้น หากไม่มีค่าที่รายงานให้เลือกเอง เปลี่ยนค่าจริงที่เอนจิน

ตัวอย่างคำขอ

curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
  -H "Authorization: Bearer $FS_BOT_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"action":"agent_environment","environment":{"cpu":"Apple M4","engine":"MyEngine","os":"Darwin","engine_threads":1,"hash_mb":32,"ponder":false}}'
Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_environment","environment":{"cpu":"Apple M4","engine":"MyEngine","os":"Darwin","engine_threads":1,"hash_mb":32,"ponder":false}}'

ตัวอย่างคำตอบ

{
    "ok": true,
    "bot": {
        "id": 2,
        "name": "MyBot",
        "owner_id": "example",
        "owner_name": "Example",
        "owner": {
            "player_id": "example",
            "name": "Example",
            "photo": "/img/no_profile.gif",
            "country_code": "",
            "country_name": "",
            "country_flag_url": "",
            "donor": false,
            "verified_player_id": ""
        },
        "engine_level": null,
        "rating": {
            "rating": 1200,
            "rd": 300,
            "official": false,
            "official_progress": {
                "kind": "provisional",
                "current": 0,
                "required": 50
            },
            "color": "pz-rating-unofficial",
            "high_rating": 1200,
            "wins": 0,
            "losses": 0,
            "draws": 0,
            "streak": 0,
            "best_streak": 0
        },
        "supported_games": ["std", "anti"],
        "auto_match": true,
        "bio": "",
        "registered_at": "2026-11-12 18:00:00",
        "registered_at_ts": 1794474000,
        "environment": {
            "cpu": "Apple M4",
            "engine": "MyEngine",
            "os": "Darwin",
            "practice": false,
            "engine_threads": 1,
            "hash_mb": 32,
            "ponder": false
        },
        "env": {
            "cpu": "Apple M4",
            "engine_threads": 1,
            "hash_mb": 32,
            "hash_mb_reported": 32,
            "hash_mb_override": null,
            "ponder": false,
            "ponder_reported": false,
            "ponder_override": null,
            "cpu_override": null,
            "engine_threads_override": null,
            "cpu_reported": "Apple M4",
            "engine_threads_reported": 1
        },
        "is_builtin": false,
        "online": true,
        "disabled": false,
        "deleted": false,
        "photo": "/flipsight/bot_match_api.php?action=photo&bot_id=2&v=1794474000000"
    },
    "server_now_ms": 1800000000000
}

POST agent_challenge

ท้าประลอง

ระบุคู่แข่งด้วย target_id (หมายเลขบอต) หรือ target_name (ชื่อบอต) ซึ่งดูได้ในหน้าบอต บอต FlipSight ในตัว (is_builtin: true) ท้าผ่าน API ได้ในเกมทุกประเภท และเซิร์ฟเวอร์จะเริ่มการแข่งทันที ถ้ามีเกมรูปแบบอื่นกับบอตในตัวกำลังแข่งอยู่ 2 การแข่งแล้ว จะได้ HTTP 409 พร้อม site bot variant matches are fullหากบอทเป้าหมายปิด "คำท้าจากบอท" ในการจัดการบอทไว้ จะได้รับ HTTP 409 พร้อม bot does not accept bot challenges เกมอัตโนมัติระหว่างบอทไม่ขึ้นกับการตั้งค่านี้และเป็นไปตามการตั้งค่าจับคู่อัตโนมัติ

ท้าบอตตัวเดิมได้สามครั้งติดต่อกัน รอห้านาทีหลังจบแมตช์ที่สามก่อนท้าอีกครั้ง

ท้าประลองจากหน้าบอต

พารามิเตอร์ชนิดจำเป็นคำอธิบาย
actionstring "agent_challenge"จำเป็นชื่อแอ็กชันที่จะเรียก
target_idinteger ≥ 1ไม่บังคับID ของบอตที่จะท้า
target_namestringไม่บังคับชื่อของบอตที่จะท้า (แทน target_id)
game_modestring std | anti | octagon | grand | reversiไม่บังคับเกมสำหรับการแข่งระหว่างบอต ค่าเริ่มต้นคือ std บอตทั้งสองต้องรองรับ มาตรฐาน / Anti / Octagon / Grand (10x10) / รีเวอร์ซีคลาสสิก

ตัวอย่างคำขอ

curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
  -H "Authorization: Bearer $FS_BOT_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"action":"agent_challenge","target_id":2,"game_mode":"anti"}'
Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_challenge","target_id":2,"game_mode":"anti"}'

ตัวอย่างคำตอบ

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

POST agent_accept

ยอมรับ

พารามิเตอร์ชนิดจำเป็นคำอธิบาย
actionstring "agent_accept"จำเป็นชื่อแอ็กชันที่จะเรียก
match_idinteger ≥ 1จำเป็นID การแข่งขัน (ติดลบสำหรับเกมกับคน)

ตัวอย่างคำขอ

curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
  -H "Authorization: Bearer $FS_BOT_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"action":"agent_accept","match_id":123}'
Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_accept","match_id":123}'

ตัวอย่างคำตอบ

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

POST agent_reject

ปฏิเสธ

พารามิเตอร์ชนิดจำเป็นคำอธิบาย
actionstring "agent_reject"จำเป็นชื่อแอ็กชันที่จะเรียก
match_idinteger ≥ 1จำเป็นID การแข่งขัน (ติดลบสำหรับเกมกับคน)

ตัวอย่างคำขอ

curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
  -H "Authorization: Bearer $FS_BOT_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"action":"agent_reject","match_id":123}'
Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_reject","match_id":123}'

ตัวอย่างคำตอบ

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

POST agent_move

ส่งตาเดิน

พารามิเตอร์ชนิดจำเป็นคำอธิบาย
actionstring "agent_move"จำเป็นชื่อแอ็กชันที่จะเรียก
match_idinteger ≠ 0จำเป็นID การแข่งขัน (ติดลบสำหรับเกมกับคน)
round_nointeger ≥ 0จำเป็นเมื่อเล่นกับคนเฉพาะเกมกับคน: round_no จากออบเจ็กต์การแข่งขัน
room_created_atstringจำเป็นเมื่อเล่นกับคนเฉพาะเกมกับคน: room_created_at จากออบเจ็กต์การแข่งขัน
leginteger 0 | 1จำเป็นเกม 0 หรือ 1 (0 สำหรับเกมกับคน)
revisioninteger ≥ 0จำเป็นrevision ของเกมที่ใช้คำนวณตาเดิน หากเกมเปลี่ยนไปแล้วจะได้ 409 stale_revision
moveinteger -1..99 | stringจำเป็นช่อง 0-(board_size²−1), -1 สำหรับการผ่าน / d3 / D3 / pass
evalnumber -100..100ไม่บังคับค่าประเมินของเอนจินคุณหลังตานี้ เป็นจำนวนหมากจากฝั่งของคุณ (+ แปลว่าคุณนำ เก็บทศนิยม 2 ตำแหน่ง) ค่าสูงสุดคือจำนวนช่องที่เดินได้ คือ 8x8 ช่วง -64 ถึง 64, 10x10 ช่วง -100 ถึง 100 และแปดเหลี่ยมช่วง -88 ถึง 88 ถ้าไม่ส่งหรือค่าไม่ถูกต้อง จะทิ้งเฉพาะค่าประเมินและยังรับตาเดินตามปกติ เฉพาะการแข่งระหว่างบอตที่เก็บค่านี้ ทุกคนเห็นระหว่างเกมรวมถึงบอตคู่แข่ง และเกมกับคนจะไม่ใช้ค่านี้

ตัวอย่างคำขอ

curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
  -H "Authorization: Bearer $FS_BOT_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"action":"agent_move","match_id":123,"leg":1,"revision":0,"move":2,"eval":1.5}'
Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_move","match_id":123,"leg":1,"revision":0,"move":2,"eval":1.5}'

คนกับบอตที่ลงทะเบียน

curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
  -H "Authorization: Bearer $FS_BOT_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"action":"agent_move","match_id":-45,"leg":0,"revision":0,"move":"d3","round_no":1,"room_created_at":"2026-11-12 19:00:00"}'
Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_move","match_id":-45,"leg":0,"revision":0,"move":"d3","round_no":1,"room_created_at":"2026-11-12 19:00:00"}'

ตัวอย่างคำตอบ

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

POST agent_games

ดาวน์โหลดบันทึกเกม

ส่งคืนเกมที่จบแล้วของบอตคุณเป็นบันทึกเกม การตอบกลับเป็น NDJSON (Content-Type application/x-ndjson) บรรทัดละหนึ่งเกม รวมการแข่งระหว่างบอตและเกมกับคน แต่ไม่รวมเกมฝึกและเกมกับบัญชีของเว็บไซต์เอง othelloclub เกมที่เป็นโมฆะทางเทคนิคก็รวมไว้ด้วยค่า result void

คำขอนี้ไม่ทำให้บอตของคุณแสดงเป็นออนไลน์ และไม่นับในการตรวจข้อกำหนด API v2 บอตแต่ละตัวเรียกได้หนึ่งครั้งทุก 5 วินาที ถ้าเรียกเร็วกว่านั้นจะได้ 429 พร้อม retry_after_sec ส่ง Accept-Encoding: gzip เพื่อรับการตอบกลับแบบบีบอัด

พารามิเตอร์ชนิดจำเป็นคำอธิบาย
actionstring "agent_games"จำเป็นชื่อแอ็กชันที่จะเรียก
sinceinteger ≥ 0ไม่บังคับupdated_ms ที่เก่าที่สุดที่จะรวม หน่วย ms ค่าเริ่มต้น 0
untilinteger ≥ 0ไม่บังคับupdated_ms ที่ใหม่ที่สุดที่จะรวม หน่วย ms ค่าเริ่มต้น: ตอนนี้
maxinteger 1..300ไม่บังคับจำนวนเกมสูงสุดต่อการตอบกลับ 1 ถึง 300 ค่าเริ่มต้น 100
gamesarrayไม่บังคับเกมที่จะรวม (std, anti, octagon, grand, reversi) ค่าเริ่มต้น: ทั้งหมด
orderstring asc | descไม่บังคับasc: เก่าก่อน (ค่าเริ่มต้น) desc: ใหม่ก่อน

ตัวอย่างคำขอ

curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
  -H "Authorization: Bearer $FS_BOT_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"action":"agent_games","since":1799913600000,"max":100}'
Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_games","since":1799913600000,"max":100}'

ตัวอย่างคำตอบ

{
    "format": 1,
    "kind": "bot",
    "id": 123,
    "url": "https://othelloclub.com/flipsight/lab?match_id=123",
    "game_mode": "std",
    "opening_mode": "random12",
    "board_size": 8,
    "time_limit_sec": 60,
    "auto": true,
    "ranked": true,
    "rating_applied": true,
    "status": "finished",
    "finish_reason": "discs",
    "result": "win",
    "started_ms": 1799999962428,
    "finished_ms": 1800000000000,
    "updated_ms": 1800000000000,
    "me": {
        "bot_id": 2,
        "name": "MyBot",
        "engine": "MyEngine",
        "rating_before": 2138.51,
        "rating_after": 2143.53
    },
    "opponent": {
        "kind": "bot",
        "bot_id": 9,
        "name": "Ethan",
        "builtin": true,
        "engine": null,
        "rating_before": 2017.41,
        "rating_after": 2017.41
    },
    "discs": [73, 55],
    "opening": "e6f6d3e7f5e3f7c4",
    "opening_squares": [44, 45, 19, 52, 37, 20, 53, 26],
    "opening_colors": "BWBWBWBW",
    "legs": [
        {
            "my_color": "W",
            "status": "finished",
            "discs": [28, 36],
            "result_discs": [28, 36],
            "colors": "BWB",
            "moves": "f3f4c3",
            "squares": [21, 29, 18],
            "at_ms": [1799999962491, 1799999965034, 1799999965089],
            "used_ms": [63, 1111, 55],
            "left_ms": [59937, 58889, 59882],
            "evals": [null, -1.5, null]
        },
        {
            "my_color": "B",
            "status": "finished",
            "discs": [37, 27],
            "result_discs": [37, 27],
            "colors": "BWB",
            "moves": "b3b4c3",
            "squares": [17, 25, 18],
            "at_ms": [1799999963923, 1799999964158, 1799999965481],
            "used_ms": [1495, 235, 1323],
            "left_ms": [58505, 59765, 57182]
        }
    ]
}

บันทึกเกม

บันทึกเกม (record) คือออบเจ็กต์ JSON หนึ่งชิ้นของเกมที่จบแล้วหนึ่งเกม ในนั้นมีผู้เล่น ผลการแข่ง เรตติ้ง การเปิดเกม และเวลาของทุกตาเดิน จากฝั่งบอตของคุณ คุณได้รับออบเจ็กต์เดียวกันนี้จากสองที่

  1. เหตุการณ์จบเกม: เมื่อเกมจบ เหตุการณ์ match สุดท้าย (status finished หรือ aborted) จะมี record มาด้วย
  2. agent_games: ส่งคืนเกมที่จบแล้ว บรรทัดละหนึ่งเกม ใช้สำหรับเกมที่ผ่านมาและเกมที่คุณพลาดไป

ตาเดินใช้รูปแบบการจดตาเดินของเว็บไซต์ ตาละสองตัวอักษร และการผ่านคือ pa คอลัมน์คือ a ถึง j และแถวคือ 1 ถึง 9 บน 10×10 แถวที่สิบคือ 0 (j0 คือช่อง 99) squares ให้ตาเดินเดียวกันเป็นหมายเลขช่อง (-1 สำหรับการผ่าน) และ colors ให้ฝ่ายที่เดินเป็น B หรือ W

เกมที่จบระหว่างที่สตรีมของคุณขาด และเกมกับคนที่บันทึกเกมยังไม่พร้อม จะไม่มี record ในเหตุการณ์จบเกม ให้เติมช่องว่างเหล่านี้ด้วย agent_games ตามขั้นตอนด้านล่าง

  1. จุดเริ่มต้น: ส่ง updated_ms ของบันทึกเกมล่าสุดที่คุณเก็บไว้เป็น since since รวมเวลานั้นเองด้วย บันทึกเกมสุดท้ายของคุณจึงส่งมาอีกครั้ง
  2. ข้ามรายการซ้ำ: ข้ามบันทึกเกมที่คุณมี kind และ id นั้นอยู่แล้ว
  3. หน้าถัดไป: เรียกอีกครั้งด้วย updated_ms ล่าสุดที่ได้รับ หยุดเมื่อการตอบกลับไม่มีบันทึกเกมใหม่
  4. บันทึกเกมที่เปลี่ยน: เกมที่เปลี่ยนหลังจบไปแล้ว เช่น โมฆะทางเทคนิค จะส่งมาอีกครั้งพร้อม updated_ms ที่ใหม่กว่า ให้แทนที่บันทึกเกมเก่าด้วยอันใหม่

agent_games

ฟิลด์ของบันทึกเกม
ฟิลด์ชนิดคำอธิบาย
formatintegerเวอร์ชันของรูปแบบบันทึกเกม ตอนนี้คือ 1 เวอร์ชัน 1 อาจมีฟิลด์ใหม่เพิ่มเข้ามา และหมายเลขจะเพิ่มขึ้นก็ต่อเมื่อความหมายของฟิลด์ที่มีอยู่เปลี่ยน
kindstringbot: การแข่งระหว่างบอตที่มีสองเกม human: เกมกับคนที่มีเกมเดียว
idintegerID ของการแข่งระหว่างบอตเมื่อ kind เป็น bot และ ID ของเกมเมื่อ kind เป็น human kind และ id รวมกันใช้ระบุบันทึกเกมหนึ่งรายการ
urlstringหน้าสำหรับดูเกมย้อนหลัง
room_id, round_nointeger | nullเฉพาะเกมกับคน: ห้องและรอบ
game_modestringเกม (std, anti, grand, octagon, reversi)
opening_modestringrandom12: การเริ่มแบบสุ่ม 12 หมากของการแข่งระหว่างบอต xot หรือ std: วิธีเริ่มของเกมกับคน
board_sizeinteger 8 | 10จำนวนช่องต่อด้าน 8 หรือ 10
time_limit_secintegerจำนวนวินาทีต่อเกม ต่อสี
autobooleanสร้างโดยการจับคู่อัตโนมัติ
rankedbooleanการแข่งขันคิดอันดับหรือไม่
rating_appliedbooleanผลการแข่งเปลี่ยนเรตติ้งหรือไม่
statusstringfinished หรือ aborted เมื่อเป็นโมฆะทางเทคนิค
finish_reasonstring | nullเหตุที่เกมจบ: การแข่งระหว่างบอตใช้ค่าเดียวกับ state.finish_reason ส่วนเกมกับคนใช้ค่าของห้องเกม
resultstringwin, loss, draw หรือ void จากฝั่งบอตของคุณ
started_ms, finished_ms, updated_msinteger | nullเวลาเริ่มและเวลาจบ หน่วย ms ส่วนในเกมกับคน started_ms เป็น null updated_ms คือเวลาที่บันทึกเกมเปลี่ยนครั้งล่าสุด ปกติคือเวลาจบ และ since กับ until เทียบกับค่านี้
meobjectบอตของคุณ: bot_id, name, engine, rating_before, rating_after engine คือชื่อเอนจินที่รายงานตอนเริ่ม และเรตติ้งทั้งสองค่าเป็น null เมื่อเกมไม่คิดเรตติ้ง
opponentobjectคู่แข่ง: kind (bot, human หรือ guest), name, engine, rating_before, rating_after บอตมี bot_id และ builtin เพิ่ม ส่วนคนมี player_id
discs[integer, integer]คะแนนของบอตคุณและคู่แข่ง: การแข่งระหว่างบอตคือผลรวมของทั้งสองเกม (state.totals) ส่วนเกมกับคนคือจำนวนหมาก
opening, opening_squares, opening_colorsstring, integer[], stringตาเปิดเกมก่อนเริ่มแต่ละเกมในรูปแบบการจดเดียวกัน: การเริ่มแบบสุ่ม 12 หมาก หรือการเปิดเกม XOT
legs[].my_colorstringสีของบอตคุณในเกมนี้ B หรือ W
legs[].statusstringactive, finished, timeout, stopped
legs[].discs[integer, integer]จำนวนเม็ดเรียงตามสี (ดำ, ขาว)
legs[].result_discs[integer, integer] (optional)คะแนนตัดสิน [ดำ, ขาว] ของเกมที่แพ้เพราะหมดเวลา (ไม่บังคับ) หากมีค่านี้ ให้ใช้รวมแทนจำนวนหมาก (discs) คะแนนของฝ่ายที่หมดเวลาและคู่แข่ง: std และ reversi 0 ต่อ 64, grand 0 ต่อ 100, octagon 0 ต่อ 88, anti 64 ต่อ 0 อีกเกมหนึ่งเล่นต่อไป และเมื่อทั้งสองเกมจบ ผลรวมจะตัดสินผู้ชนะ บันทึกที่จบไปแล้วก่อนหน้านี้จะไม่ถูกคำนวณใหม่
legs[].moves, squares, colorsstring, integer[], stringตาเดินของเกมนั้นหลังการเปิดเกม: moves เป็นสตริง squares เป็นตัวเลข colors เป็น B หรือ W ของแต่ละตา
legs[].at_ms, used_ms, left_ms(integer | null)[]สำหรับแต่ละตา: เวลาที่เดิน หน่วย ms เวลาที่ใช้ และเวลาที่เหลือของฝ่ายที่เดินหลังเดินตานั้น ในเกมกับคน เวลาที่เดินเป็น null และค่าที่ไม่ทราบก็เป็น null
legs[].evals(number | null)[] (optional)ค่าประเมินที่ฝ่ายที่เดินส่งมากับตาเดิน เป็นจำนวนหมากจากฝั่งของฝ่ายนั้น ตาที่ส่งมาโดยไม่มีค่าประเมินเป็น null ถ้าในเกมนั้นไม่มีตาใดมีค่าประเมินเลย จะไม่มีฟิลด์นี้

ข้อผิดพลาด

ข้อผิดพลาดมีรูปแบบ {"ok": false, "error": "…"} หากได้ 401 ให้หยุดและตรวจโทเคน หากได้ 409 ให้ตรวจตาเดิน revision และตาที่ถูกกติกาจากสถานะล่าสุดที่คุณมี (ถ้าไม่แน่ใจให้เชื่อมต่อสตรีมใหม่) 410 หมายถึงคำสั่งนั้นถูกยกเลิกแล้ว (agent_poll ตั้งแต่ 2026-11-22 00:00 (UTC+9)) ให้ใช้สตรีมเหตุการณ์แทน 429 หมายถึงคำขอมากเกินไป (บอตหนึ่งตัวเกิน 20 ครั้งต่อวินาที หรือบอตทุกตัวใน IP เดียวกันรวมกันเกิน 40 ครั้งต่อวินาทีที่ bot_match_api.php) เมื่อได้ 429, 5xx หรือข้อผิดพลาดการเชื่อมต่อ ให้ส่งคำขอเดิมซ้ำหลัง 0.2-0.5 วินาที (ถ้ามี Retry-After ให้ทำตาม) แล้วค่อยเพิ่มเวลารอหลังลองไปสองสามครั้ง และอย่าส่งตาที่ผิดกติกาซ้ำ

{"ok":false,"error":"stale_revision","server_now_ms":1800000000000}
HTTPerror
400JSON object required / unknown action
401invalid bot credential
403access denied / invalid csrf
405POST required
409stale_revision / not_your_turn / illegal_move / leg_finished / match not running / match timed out / stale room revision / invalid move coordinate / move outside board / unsupported game mode / both bots must be connected / bot already has an active match / bot busy / engine thread limit exceeded / bot challenge repeat limit / challenge expired or answered / site bot variant matches are full / target bot not found
410agent_poll was removed; use bot-stream
413request too large
429Too many requests (bot_match_api.php rate limit)
503bot match storage unavailable

agent_poll
อ่านสถานะ (ยกเลิก 2026-11-22)

ยกเลิกในวันที่ 2026-11-22 00:00 (UTC+9) หลังจากนั้นจะตอบกลับ HTTP 410 {"ok": false, "error": "agent_poll was removed; use bot-stream"} ให้รับสถานะจากสตรีมเหตุการณ์ และเชื่อมต่อสตรีมใหม่เพื่อซิงก์ใหม่ ก่อนถึงเวลานั้นยังตอบอยู่ แต่ตั้งแต่ 2026-11-21 23:40 (UTC+9) บอทที่ลงทะเบียนซึ่งเรียกคำสั่งนี้ใน 10 นาทีล่าสุดจะไม่ได้รับการจับคู่อัตโนมัติ

เขียนการเชื่อมต่อ API เอง
Copyright © Othelloclubthe.othelloclub.com@gmail.com All rights reserved.