Gomoku Protocol [译]

0 译序

动机 —— 研究学习五子棋 AI 的同时，对比了很多支持主流五子棋 AI 的 GUI。

结论是：都有一些体验不佳之处，决定自定写一个。要与 AI 程序交互，需要适配 AI 的接口，因此翻译这篇文章 Gomoku New protocol

意图 —— 研究过接口协议后，五子棋 GUI 的实现

• 对主流 AI 的支持
• 人人对战、人机对战、机机对战
• 良好的用户体验、高度定制
• 跨平台、易扩展
• 恰当的开源协议

1 简介

此文档描述了一个 AI (Artificial Intelligence) 如何与 go-moku 管理器(一个管理和控制比赛的程序)进行交互。

管理器创建两个管道：

• 第一个用来从管理器向 AI 发送指令
• 第二个则从 AI 向管理器传递响应

该 AI 使用标准输入/输出函数(如：C 语言的 scanf 和 printf ，Pascal 的 readln 和 writeln )因而可以使用任何编程语言编写。该 AI 程序必须是一个控制台应用程序，没有 GUI 界面。

注意！

一些运行时库会缓存输出，比如：在 C 的 printf 之后需要调用fflush(stdout) AI 实现者也可以调用一些低级的函数： ReadFile 和 WriteFile

每一行包含一条指令（只有一个例外）。管理器采用 CR LF (0x0d,0x0a) 标识一行的结束。AI 则可以用 CR LF， LF 或 CR 来标识响应行的结尾。管理器将忽略空的行。如何行内容过长，可以静默的截断该行但程序不能崩溃。

如果 AI 是单线程的，则在 AI 在进行思考或响应一条指令时，不要读取输入，否则导致死锁（AI 和 管理器均进入等待状态）。在上述情况下，一个回合的时限达到后，管理器将终止 AI 程序。

AI 可以使用两个线程来避免上述问题。一个线程读取指令，而另一个负责计算和回写响应。鉴于多个线程的方案，同步机制也必须引入（事件、锁、信号量等）。

AI 的线程数对于比赛来说并不重要，一个线程比赛足够了。但是两个线程对于人类玩家来说很有用，比如有的人可能想在 AI 思考过程中改变比赛时限。

AI 的思考应该可以中断而不必关闭 AI 程序。

AI 必须处理这些指令： START BEGIN INFO BORAD TURN END 。如果接受到除此之外的指令则统一返回： UNKNOWN (为了向后兼容以及未来的协议扩展)

2 AI 名称与临时文件

AI 名称只能包含：英文字母 [A-Za-z]、阿拉伯数字 [0-9]、横杠 (-)、下划线 (_)和点 (.)。程序名比如以 pbrain- 为前缀

例如：

1pbrain-swine.exe
2pbrain-pisq5.exe

前缀的要求仅限制可执行程序的名称，压缩打包文件本身没有此限制。压缩打包文件中可以同时包含 32位 和 64位 的 EXE 文件，且 64位 的可执行文件名必须包含 64 后缀

例如：

1MyGomo.zip
2|-- pbrain-MyGomo.exe
3|-- pbrain-MyGomo64.exe

籍此，管理器可以在不同的平台上，选择适配的程序。

工作目录由管理器来设定，该目录不必与 AI 程序所在路径相同，AI 必须用完整路径来指出其所使用的所有数据文件的位置。该路径可以通过函数 GetModuleFileName 或者程序启动时的命令行参数获得。管理器必须采用上述方式启动 AI 程序，使得 AI 程序可以打开那些数据文件。

AI 可以在当前目录创建一个文件夹来存储临时文件。该目录的名称必须与 AI 的名称一致，该目录的大小限制在 Gomocup 网页中描述（当前为 20MB）。当管理器退出时，或比赛结束时，管理器可以删除所有临时文件。

指令 INFO folder 用来指定需要持久保存的文件的位置。

3 强制指令

3.1 START [size]

AI 接收到此指令时，执行自身初始化并绘制一个空棋盘，但此时没有任何行棋的动作。

参数 size 用来指定棋盘的大小，AI 必须支持 20x20 大小的棋盘¹，这是 Gomocpu 锦标赛的规定尺寸。

建议但不强制 AI 支持其他尺寸的棋盘，若 AI 不支持指令给出的尺寸，则需以 ERROR 响应

1管理器发送:
2	START 20
3AI 回答：
4	OK # 一切正常
5	ERROR <message> # 不支持的棋盘尺寸或其他错误

3.2 TURN [X],[Y]

参数 [X],[Y] 表示对手的落子位置，横纵坐标都属于 [0,N] ，其中 N 为自然数。

1管理器发送：
2      TURN 10,10
3AI 回答：
4      11,10

3.3 BEGIN

此指令在一局比赛的开始，由管理器发送给其中一个 AI。表明期望该 AI 在一个空棋盘上开始行棋。之后其他的 AI 通过接收 TURN 指令的方式得悉对手的落子。 BEGIN 指令在启用自动开局时将不被使用，这是因为参赛的双方 AI 都将接收 BOARD 指令

1管理器发送：
2      BEGIN
3AI 回答：
4      10,10

3.4 BOARD

此指令强制规定整个行棋局面。适合从中途延续一局比赛、或执行撤销/重做等用户指令的场景。

BOARD 指令通常在 START ， RESTART 或 RECTSTART 指令之后执行，此时棋盘为空。如果当前有任何比赛在进行中，管理器将在发送 BOARD 指令前发送 RESTART 指令

BOARD 指令之后，发送局面数据，格式为：

[X],[Y],[field]

其中：

[X],[Y] 为坐标

[field] 为：

• 1 表示自己的落子
• 2 表示对手的落子
• 3 仅在设置了持续行棋选项后，表示胜利线中的落子，或者(renju规则)禁手点

如果是 renju 规则，则管理器必须按照真实的行棋顺序发送局面数据。

如果是 Gomoku 规则，则管理器可以用任意顺序发送局面数据，且 AI 需自行处理这些数据。

数据发送完成后，管理器发送 DONE 指令通知 AI，用以期望 AI 的计算应答，以及后续的 TURN 或 BEGIN 指令

1管理器发送：
2      BOARD
3      10,10,1
4      10,11,2
5      11,11,1
6      9,10,2
7      DONE
8AI 回答：
9      9,9

3.5 INFO [key] [value]

AI 可以忽略这条指令。然而，若无限制的忽略则直接判负。

AI 必须能够应对管理器没有通过INFO指令给出下面文档中提到的全部信息的情况。

下列信息全部在一局比赛开始时发送，锦标赛期间时限信息将不被修改。

建议 AI 在任何情况下都响应该指令，因为人类对手可以在 AI 思考过程中修改下列信息

1timeout_turn  - time limit for each move (milliseconds, 0=play as fast as possible)
2timeout_match - time limit of a whole match (milliseconds, 0=no limit)
3max_memory    - memory limit (bytes, 0=no limit)
4time_left     - remaining time limit of a whole match (milliseconds)
5game_type     - 0=opponent is human, 1=opponent is brain, 2=tournament, 3=network tournament
6rule          - bitmask or sum of 1=exactly five in a row win, 2=continuous game, 4=renju
7evaluate      - coordinates X,Y representing current position of the mouse cursor
8folder        - folder for persistent files

时限和内存限制在第一步棋之前发送(在 START 指令之前、或紧跟 START )；

time_left 在每一步棋之前发送(也就是 TURN , BEGIN 和 BOARD 之前)；

当 AI 超时的情况下，剩余时间可以是负值；

对于无时限的对局，剩余时间为：2147483647；

对于有时限的对局，管理器必须发送 time_left，从而 AI 可以忽略 timeout_match 仅响应 time_left

一局比赛的时间是从进程创建到比赛结束（但不包含对手回合的时间），一个回合的时间包含除了初始化指令( START , RECTSTART , RESTART )的全部时间，回合时限为 0 表示 AI 应该尽可能快的行棋（例如：只进行静态评估而不搜索可能的行棋）

INFO folder 用来指定需要被持久化的文件保存到哪里。由于这些文件对于其他 AI 和程序都是可见的，因此 AI 必须创建自己的子目录，目录名与 AI 名一致。如果管理器没有发送 INFO folder，则 AI 不能持久保存文件

只有调试版本的程序才应该响应 INFO evaluate 指令，比如在某些窗口中打印评估信息，这些信息不应该打印到标准输出。发布版本的程序应该忽略 INFO evaluate

问：AI 接收到不认识的 INFO 怎么办

答：忽略，该指令大概不重要；如果他是重要的，就不该出现在 INFO 中

问：AI 接收到不现实的 INFO 怎么办(比如：特别小的内存限制值)

答：AI 应该在标准输出上等待，直到管理器发送一个非 INFO 指令( TURN , BOARD or BEGIN )，管理器发送 INFO 指令时并不读取 AI 的响应

1INFO timeout_match 300000
2INFO timeout_turn 10000
3INFO max_memory 83886080
4 
5# 没有期待的响应

3.6 END

AI 在接收到这条指令时应该尽快中止。管理器等待 AI 自行完成，但若中止过程太久（比如1秒），则管理器将结束 AI 进程。AI 在接收到 END 指令后，不应该在标准输出上写任何信息。但在 AI 进程结束前，管理器不要关闭管道。

AI 应该删除其临时文件

3.7 ABOUT

管理器期望 AI 在一个行内给出自身的一些信息，信息的格式为 key="info"，多个信息用逗号隔开，建议的 key 包括：name, version, author, country, www, email。管理器应当识别这些信息，但是也必须能够应对旧版 AI 中曾经使用的非结构化的人类习惯文本

1管理器发送：
2      ABOUT
3AI 回答：
4      name="SomeBrain", version="1.0", author="Nymand", country="USA"

4 可选命令

本章节中的扩展命令在 Gomocup 锦标赛中并不强制要求支持，但在人类对弈过程中是很有用的。

4.1 RECTSTART [width],[height]

与 START 类似，区别在于棋盘为矩形。[width] 描述横轴，[height] 描述纵轴。若棋盘为正方形则必须使用 START

1管理器发送：
2      RECTSTART 30,20
3AI 回答：
4      OK # parameters are good
5      ERROR message # rectangular board is not supported or other error

4.2 RESTART

该指令在一局比赛结束或中止后执行。棋盘尺寸不变。AI 释放上一局的棋盘和其他资源，创建一个新的空棋盘并使自己准备开始新的一局比赛，准备停当后 AI 回写 OK 并等待后续的对局指令。如果 AI 回答 UNKNOWN ，管理器将发送 END 并重新运行 AI 进程

1管理器发送：
2      RESTART
3AI 回答：
4      OK

4.3 TAKEBACK [X],[Y]

该指令用于撤销最后的一步行棋，AI 移除 [X],[Y] 处的落子后回答 OK

1管理器发送：
2      TAKEBACK 9,10
3AI 回答：
4      OK

4.4 PLAY [X],[Y]

仅当 AI 发送 SUGGEST 指令时，用来强制 AI 行棋在 [X],[Y]

期望的响应：与 PLAY 指令指定的 [X],[Y] 相同；若 AI 不认同管理器发送的坐标，其可以回答一个不同于 PLAY 指令的坐标，但行棋位置必须按照 PLAY 指令指定的位置落子

1AI 发送：
2      SUGGEST 10,10
3管理器发送：
4      PLAY 12,10
5AI 在 12,10 落子并且回答:
6      12,10

5 由 AI 发送的指令

以下指令由 AI 按需发送，管理器必须能够识别这些指令

5.1 UNKNOWN [error message]

AI 发送此指令，表明其接收到了未知的或未实现的指令。这意味着在 AI 接收到奇怪的指令时不是退出程序。

指令后跟随的消息被用来通过管理器展现给用户。若管理器发送的可选指令未由 AI 实现，则管理器应当转而发送强制指令。

5.2 ERROR [error message]

AI 发送此指令，表明其接收到了已经实现的指令，但是在处理过程中出现了错误。比如内存限制太小或者棋盘尺寸太大。

指令后跟随的简短消息将由管理器写入日志窗口或日志文件。

管理器也可是试图修改一些游戏选项并重发指令！

5.3 MESSAGE [message]

发送给用户的消息。管理器可以将该消息写入日志窗口或日志文件。期望的是，AI 在响应管理器的一些指令之前，发送这些消息。一条消息中不可以有换行符，多行文本应该拆分成多个 MESSAGE 指令发送给管理器

建议之发送英文消息。若 AI 发送其他语种的消息，其应该检测系统的 code page 并且不要发送该 code page 中无法显示的字符

5.4 DEBUG [message]

与 MESSAGE 指令类似，但仅面向 AI 的作者提供调试信息。这些信息在 Gomocup 锦标赛中将不被公开可见。

1管理器发送：
2      TURN 10,15
3AI 回答:
4      DEBUG The most promising move now is [10,14] alfa=10025 beta=8641
5      DEBUG The most promising move now is [11,14] alfa=10125 beta=8641
6      MESSAGE I will be the winner  
7      10,16

5.5 SUGGEST [X],[Y]

AI 可以自行推荐行棋的坐标，而内部的局面状态并不改变。管理器可能忽略 AI 的建议而强制另一个坐标给 AI。期望的管理器应答是 PLAY 或者 END 指令。

在 Gomocup 锦标赛中，管理器始终采纳 AI 在SUGGEST指令中给出的行棋位置。大多数 AI 都不使用此指令