浅红象棋插件说明

QHPLUGIN V1.3
Jeremy Craner
2004/07/03
www.jcraner.com/qianhong/

插件说明

想写一个 AI 引擎为浅红吗? 它不是太难如果你有一些编程经验和一个 Windows/DOS 编译器.

它产生外加的插件能力, 浅红是一种像 WinBoard为中国象棋. 我没有听说过 WinBoard在我制作插件前, 但是构造是很简单的: 一个 GUI(图形用户界面) 用来传送 I/O(输入/输出) 到通话和 AI引擎. 也许浅红会成长成一种象棋 WinBoard... 谁知道. 看一下 WinBoard 站点, 虽然, 它显示出 WinBoard经验丰富并有大量的追随者.

下列页描述了浅红的插件协议:

1. 总论
2. 插件模式
3. 命令
4. Tricky Stuff

1. 插件总论

浅红 AI 插件是一个简单的 Windows控制台程序,它能够读入标准的输入并写入标准的输出. 浅红运行插件执行的像一个分离的过程用它的标准 I/O 变址到匿名的通道. 一个文本基础协议, 它由一组简单的命令组成, 被用来与插件通信.

作为一个例子, 下面的文本显示了一个棋局的第一部分对战 QHPlugin.exe (默认的浅红 AI引擎) 以三个级别设定:

LEVEL 3                  (浅红设置 AI 级别)
OK - Set AI level to 3   (插件接受它)
PLAY H2-E2               (浅红走一步棋: round 1, red)
OK                       (插件接受它)
AI                       (浅红询问AI走棋)
B9-C7                    (插件走一步棋: round 1, black)
PLAY E2-E6               (浅红走一步棋: round 2, red)
OK                       (插件接受它)
AI                       (浅红询问AI走棋)
C7-E6                    (插件走一步棋: round 2, black)
UNDO                     (浅红悔一步棋)
OK                       (插件接受它)

它是一个界面. 现在是详细资料: 2. 插件模式.

2. 插件模式

插件可以运行在两种模式之一, 通过命令行参数指定: "-info" 和 "-plugin". 信息模式用于浅红启动时. 它允许浅红询问插件的详细资料为它的能力. 插件模式用在真的下象棋时.

信息模式

当插件以 "-info" 变量运行时, 它的动作打印到标准的信息列表并退出. 信息是如下格式:

Protocol Version
AI Engine Name
LEVELS <N>
(N lines of levels)
UNDO <0/1>
HINTS <0/1>
RULES <0/1>
BGTHINK <0/1>
TIMEOUT <0/1>
(Additional lines of Info)
ENDINFO

获得信息从 QHPlugin.exe 作为一个例子 (你可以自己运行 "<Qianhong dir>\Plugins\Qianhong\QHPlugin.exe -info"):

C:\Qianhong\Plugins\Qianhong>qhplugin.exe -info
QHPLUGIN V1.3
Qianhong
LEVELS 3
1 - Very Easy
2 - Easy
3 - Smarter
UNDO 1
HINTS 1
RULES 1
BGTHINK 0
TIMEOUT 0
Qianhong AI engine for Qianhong v3.1
By Jeremy Craner, 2001-2004
ENDINFO

Protocol Version 第一行是协议的版本. 它能读取 "QHPLUGIN V1.3" (虽然 V1.2 仍然支持). 版本允许将来扩展.

AI Engine Name 第二行给出出现在棋局中的AI引擎名. 希望你使它短一些因为棋手名字框不太大...

Levels 第三行告诉你插件有多少不同的 AI级别. 下面的行列出每个级别, 一个一行, 包含数字和附加的你想要的文本描述. 级别必须指定一个数字. 附加文本 (以空格开始) 是随意的.

Undo 它告诉浅红是否支持悔棋命令. 0 表示不支持, 1 表示支持.

Hints 它告诉浅红是否支持 HINTS 命令. 0 表示不支持, 1 表示支持.

Rules 它告诉浅红是否支持 BAN 命令. 0 表示不支持, 1 表示支持.

BGThink 它告诉浅红是否支持 BGTHINK 命令. 0 表示不支持, 1 表示支持.

Timeout 它告诉浅红是否支持 TIMEOUT 命令. 0 表示不支持, 1 表示支持.

附加的信息 跟随提示行, 所有行跟随 ENDINFO 行被看作附加的信息，它出现在 "选择 AI 引擎" 对话框. 空行用来作格式化.

插件模式

当插件以 "-plugin [debug]" 参数运行, 它用于下棋. 浅红改址 STDIN 和 STDOUT 到通道以便它能和插件通话. 插件读命令从 STDIN, 采取适当的动作, 并写响应到 STDOUT. 所有命令 (除了一个, 将在下面看到)都需要响应. 插件必须激发 STDOUT每当安结束写入响应时以便数据将被发送通过通道. 激发流失败将造成浅红无限期的等待数据.

可选的 "debug" 变量被用作当浅红运行插件在调试模式时. (运行浅红以"plugin_debug" 作为第一个变量.) 在此模式下, 插件将有一个控制台并可以输入任何你想要的到控制台通过写入到 STDERR. 当然, 你也可以写入到一个文件 (或其它东西) 如果你相. 调试模式对你很有用; 好好使用吧.

下一节, 3. 命令s, 描述命令和它们关联的响应.

3. 插件命令

浅红发送下面的命令给插件. 每一个命令交详细的论述在下面. 命令和响应消息全部大写, 虽然如此你的插件也最好可以选择到识别小写命令.

  必需的:
    LEVEL [new-level]
    FEN <FEN-string>
    PLAY <ICCS-move>
    LOAD <count> ...
    AI
    ABORT
    QUIT

  可选的:
    UNDO
    HINTS
    BAN <count> ...
    BGTHINK <ON|OFF>
    TIMEOUT

关于响应的一个注解: 所有响应必须以换行符 ('\n')结束. 希望的响应以命令区分, 但是两个最普通的响应是 OK 和 ERROR. Both of these may be followed (on the same line) by additional text as desired. Errors 通常被报告在浅红的消息框, 这样用户将能读取错误的文本描述.

LEVEL

命令 LEVEL

响应 <current-level>

描述 For a LEVEL 命令 with no parameter, reply with the current level number.

命令 LEVEL <新级别>

响应s OK [文本]
ERROR [文本]

描述一个 LEVEL 命令有一个参数, 设置当前级别通过一个数字给出. 返回 OK 如果成功, 或 ERROR 如果数字超范围.

FEN

命令 FEN <FEN-string>

响应 OK [text]
ERROR [text]

描述这个命令通知插件设置棋盘使用 FEN 字符串 (参见 www.wxf.org/xq/computer/fen.pdf 为详细资料关于 FEN 为中国象棋). 红棋总是在下面 (i.e. the last line of the string). 返回 OK 如果棋盘被设定, 或 ERROR 如果有些地方不对.

PLAY

命令 PLAY <ICCS-下棋>

响应 OK [文本]
ERROR [文本]

描述它告诉插件走给定的棋步. 走子参数是 ICCS 符号形式是 "A0-A1". Looking down on a board with red on the bottom, A0 在左下角 (红棋左车的启始位) I9 在右上角(黑棋左车的启始位). 所以棋步 "A0-A1" 将移动would move the piece in the near corner of red's ninth file up one spot. (参见棋谱协议在 4. Tricky Stuff 为更多信息.) 返回 OK 如果走子成功, 或 ERROR 如果有一些地方不对.

LOAD

命令 LOAD <count> \n [ICCS-move \n] ...

响应 OK [text]
ERROR [text]

描述告诉插件播放一个棋步列表. 这允许浅红加载整个走子顺序更快的比使用 multiple PLAY 命令. 参数是走动的步数, 它在 ICCS格式被给出, 一个一行, 跟随 LOAD 命令.

AI

命令 AI

响应 <ICCS-走棋>
ERROR [text]
ABORTED

描述告诉插件为当前玩家走棋并报告棋步. 插件响应用棋步以ICCS 符号形式 "A0-A1", 或ERROR 如果有些地方不对. 如果插件的 AI引擎用多于一秒响应, 插件必须保持监视 STDIN 为新命令, 并中断 AI引擎如果命令来到在引擎完成思考之前. 这种情况下,插件应该响应用 ABORTED, 然后处理下一个命令作为作为常态.

浅红典型的中断AI 命令只在用户关闭应用程序或退出当前棋局时. 例外是和TIMEOUT命令, 它, 如果被支持, 被发送到引起 AI 停止思考并回应使用到目前为止提出来的最好的棋步.

ABORT

命令 ABORT

响应 (无)

描述 ABORT(中断) 命令被使用当一个AI 或 HINTS 命令被进行，然后浅红需要职能部门它并使插件返回到就绪状态. 既然插件必须中断 AI 和 HINTS 命令当任何新命令被发送, 这是正常的方法停止 AI引擎而不引起新命令到执行. 插件不直接响应 ABORT 命令; 唯一的响应是来自于一个停止的 AI 或 HINTS 命令 ,它以 ABORTED作为响应.

QUIT

命令 QUIT

响应 BYE

描述这个命令告诉插件停止运行并退出. 插件响应用 BYE 当它关闭时. (如果插件没有响应或关闭, 浅红将给它大约一秒的时间然后杀掉它. 这时最后的办法它使资源未解决, 所有插件应该确认关闭适度的当它被告知退出时.)

UNDO

命令 UNDO

响应 OK [文本]
ERROR [文本]

描述告诉插件取消最近的棋步. 插件响应OK当它可以撤消它时, 或 ERROR 如果有什么不对 (或如果没有走子时).

插件可以选择不执行这个命令 (to the dismay of users =) 通过指定 "UNDO 0" 在信息模式.

HINTS

命令 HINTS

响应 <hint [描述]> \n [hint [描述] \n] ... ENDHINTS
ERROR [text]
ABORTED

描述请求提示在当前的棋步从插件. 这基本上和 AI 命令相同除了: (1) 插件不走子, (2) 插件可以提示一步棋以上, (3) 插件或以描述棋步给用户.

常规的响应是一个或多个 ICCS棋步, 一个一行, 跟随一行表示 ENDHINTS. 棋步应该被列出以从好到坏的顺序; 违法的棋步必须不能被列出. 每个 ICCS 棋步应该被跟随(在同一行上) 通过附加的文本描述棋步. 其它响应是 ERROR 和 ABORTED. (既然这个命令或以花一秒以上的时间执行, 它应该被能被中断通过 ABORT 和 TIMEOUT--查看 AI 命令为更多.)

这个插件可以选择不执行这个命令 (to the dismay of users =) 通过指定 "HINTS 0" 在信息模式.

BAN

命令 BAN <count> \n [ICCS-move \n] ...

响应 OK [text]
ERROR [text]

描述告诉插件列出的棋步是考虑的违例为下一个 AI 或 HINTS 命令. 它允许浅红缓和棋局像一个裁判, 并让插件选择正确的其它棋步. 这个参数是禁止的走法的号码, 它被 ICCS 格式给出, 一个一行, 跟随 BAN 命令.

插件可以选择不执行这个命令通过指定 "RULES 0" 在信息模式. 在这种情况下, 如果插件走一个禁止的棋步, 浅红将呼叫棋局一个丧失. (丧失是不太好的, 所有插件应该支持这个命令如果可能.)

BGTHINK

命令 BGTHINK <ON|OFF>

响应 OK [文本]
ERROR [文本]

描述这个命令通知插件改变后台思考开或关. 浅红不让后台思考当两个插件互相下棋或当用户手动禁止它时. (浅红将总是通知插件转换后台思考开或关在每一个棋局开始时.)

如果插件不支持后台思考 (象指定通过 "BGTHINK 0" 在信息模式, 它不需要支持这个命令.

TIMEOUT

命令 TIMEOUT

响应 (无)

描述这个命令被浅红发送在用户指定的时间限制已到而 AI 或 HINTS 命令还没有结束时. 这个命令与 ABORT 命令相似. 实际上, 唯一不同的是 AI必须停止思考并转到一个有效的棋步或提示列出代替给出 ABORTED 响应. 像用 ABORT 命令一样, 唯一的响应是来自一个未决的 AI 或 HINTS 命令. (插件必须不发出响应如果 AI 是空闲的.)

插件应该选择不执行这个命令通过指定 "TIMEOUT 0" 在信息模式.

以上就是这些命令. 如果你有任何问题关于它们, 或如果我的描述不太清楚, 你可以这样做为更好的理解这个协议:

查看源代码 keplugin 和 VsccPlugin为一个例子.
运行浅红以 "plugin_debug" 参数并监视和插件的通信.
直接的运行插件 (跟随 "-plugin" 参数)并输入你的命令. (QHPlugin.exe 和 keplugin.exe都有一个特别的命令, SCR, 它显示棋盘帮助你跟随棋局当你手动运行时.)

下一节, 4. Tricky Stuff, 描述你在写插件时需要注意的东西.

4. 技巧

测试你的插件
当你运行浅红跟随 "plugin_debug" 参数, "选择 AI引擎" 对话显示一个按钮你可使用它运行一组测试关于插件. 使用这个特征帮助你确保插件正确的处理命令.

Piped I/O
确认闪动 STDOUT在每一个响应后!

响应时间
如果你的 AI用了多于一秒时间为 AI 和 HINTS 命令 (许多引擎都这样), 那么你必须提出一些方法以响应更快为任何引入的命令. 最好的方法是使用多线程为你的 AI 引擎. 你也可使用轮流检测, 但是你必须使用不闭塞的读取为输入.

记谱协定
Red 总是在下方为 ICCS 走子和 FEN 字符串. 下图显示了 ICCS 记谱配置和 FEN 行顺序 (行描述为从左到右):

              (Black)
     A  B  C  D  E  F  G  H  I
  9 [r][h][e][a][k][a][e][h][r] 9        (first FEN row)
     |  |  |  | \|/ |  |  |  |
  8  |--+--+--+--+--+--+--+--|  8        (2nd FEN row)
     |  |  |  | /|\ |  |  |  |
  7  |-[c]-+--+--+--+--+-[c]-|  7        (3rd FEN row)
     |  |  |  |  |  |  |  |  |
  6 [p]-+-[p]-+-[p]-+-[p]-+-[p] 6        (4th FEN row)
     |  |  |  |  |  |  |  |  |
  5  |-----------------------|  5        (5th FEN row)
     |                       |
  4  |-----------------------|  4        (6th FEN row)
     |  |  |  |  |  |  |  |  |
  3 (P)-+-(P)-+-(P)-+-(P)-+-(P) 3        (7th FEN row)
     |  |  |  |  |  |  |  |  |
  2  |-(C)-+--+--+--+--+-(C)-|  2        (8th FEN row)
     |  |  |  | \|/ |  |  |  |
  1  |--+--+--+--+--+--+--+--|  1        (9th FEN row)
     |  |  |  | /|\ |  |  |  |
  0 (R)(H)(E)(A)(K)(A)(E)(H)(R) 0        (last FEN row)
     A  B  C  D  E  F  G  H  I
               (Red)

玩家次序
红棋先行, 除非使用 FEN 命令改变到黑方先行. 当插件获得一个AI (或 HINTS) 命令, 它将下棋 (或思考)为任何一方下一步将走的棋. AI从不被明确的告知它执哪一种颜色.

后台思考
如果你执行后台思考, 你将开始思考在一个 AI 命令后, 并提前思考为那个 AI 命令为走棋的同一颜色. 如果发生一些意外的情况 (UNDO, BAN, PLAY 一个未料到的棋步, 等等.), 你将不得不终止思考. 既然一个插件只用于棋局的一方 (除了人和它自己--这时不使用 AI 命令), 你不需要获得 AI 命令从棋盘的两边.

命令	LEVEL
响应	<current-level>
描述	For a LEVEL 命令 with no parameter, reply with the current level number.

命令	LEVEL <新级别>
响应s	OK [文本] ERROR [文本]
描述	一个 LEVEL 命令有一个参数, 设置当前级别通过一个数字给出. 返回 OK 如果成功, 或 ERROR 如果数字超范围.

命令	FEN <FEN-string>
响应	OK [text] ERROR [text]
描述	这个命令通知插件设置棋盘使用 FEN 字符串 (参见 www.wxf.org/xq/computer/fen.pdf 为详细资料关于 FEN 为中国象棋). 红棋总是在下面 (i.e. the last line of the string). 返回 OK 如果棋盘被设定, 或 ERROR 如果有些地方不对.

命令	PLAY <ICCS-下棋>
响应	OK [文本] ERROR [文本]
描述	它告诉插件走给定的棋步. 走子参数是 ICCS 符号形式是 "A0-A1". Looking down on a board with red on the bottom, A0 在左下角 (红棋左车的启始位) I9 在右上角(黑棋左车的启始位). 所以棋步 "A0-A1" 将移动would move the piece in the near corner of red's ninth file up one spot. (参见棋谱协议在 4. Tricky Stuff 为更多信息.) 返回 OK 如果走子成功, 或 ERROR 如果有一些地方不对.

命令	LOAD <count> \n [ICCS-move \n] ...
响应	OK [text] ERROR [text]
描述	告诉插件播放一个棋步列表. 这允许浅红加载整个走子顺序更快的比使用 multiple PLAY 命令. 参数是走动的步数, 它在 ICCS格式被给出, 一个一行, 跟随 LOAD 命令.

命令	AI
响应	<ICCS-走棋> ERROR [text] ABORTED
描述	告诉插件为当前玩家走棋并报告棋步. 插件响应用棋步以ICCS 符号形式 "A0-A1", 或ERROR 如果有些地方不对. 如果插件的 AI引擎用多于一秒响应, 插件必须保持监视 STDIN 为新命令, 并中断 AI引擎如果命令来到在引擎完成思考之前. 这种情况下,插件应该响应用 ABORTED, 然后处理下一个命令作为作为常态. 浅红典型的中断AI 命令只在用户关闭应用程序或退出当前棋局时. 例外是和TIMEOUT命令, 它, 如果被支持, 被发送到引起 AI 停止思考并回应使用到目前为止提出来的最好的棋步.

命令	ABORT
响应	(无)
描述	ABORT(中断) 命令被使用当一个AI 或 HINTS 命令被进行，然后浅红需要职能部门它并使插件返回到就绪状态. 既然插件必须中断 AI 和 HINTS 命令当任何新命令被发送, 这是正常的方法停止 AI引擎而不引起新命令到执行. 插件不直接响应 ABORT 命令; 唯一的响应是来自于一个停止的 AI 或 HINTS 命令 ,它以 ABORTED作为响应.

命令	QUIT
响应	BYE
描述	这个命令告诉插件停止运行并退出. 插件响应用 BYE 当它关闭时. (如果插件没有响应或关闭, 浅红将给它大约一秒的时间然后杀掉它. 这时最后的办法它使资源未解决, 所有插件应该确认关闭适度的当它被告知退出时.)

命令	UNDO
响应	OK [文本] ERROR [文本]
描述	告诉插件取消最近的棋步. 插件响应OK当它可以撤消它时, 或 ERROR 如果有什么不对 (或如果没有走子时). 插件可以选择不执行这个命令 (to the dismay of users =) 通过指定 "UNDO 0" 在信息模式.

命令	HINTS
响应	<hint [描述]> \n [hint [描述] \n] ... ENDHINTS ERROR [text] ABORTED
描述	请求提示在当前的棋步从插件. 这基本上和 AI 命令相同除了: (1) 插件不走子, (2) 插件可以提示一步棋以上, (3) 插件或以描述棋步给用户. 常规的响应是一个或多个 ICCS棋步, 一个一行, 跟随一行表示 ENDHINTS. 棋步应该被列出以从好到坏的顺序; 违法的棋步必须不能被列出. 每个 ICCS 棋步应该被跟随(在同一行上) 通过附加的文本描述棋步. 其它响应是 ERROR 和 ABORTED. (既然这个命令或以花一秒以上的时间执行, 它应该被能被中断通过 ABORT 和 TIMEOUT--查看 AI 命令为更多.) 这个插件可以选择不执行这个命令 (to the dismay of users =) 通过指定 "HINTS 0" 在信息模式.

命令	BAN <count> \n [ICCS-move \n] ...
响应	OK [text] ERROR [text]
描述	告诉插件列出的棋步是考虑的违例为下一个 AI 或 HINTS 命令. 它允许浅红缓和棋局像一个裁判, 并让插件选择正确的其它棋步. 这个参数是禁止的走法的号码, 它被 ICCS 格式给出, 一个一行, 跟随 BAN 命令. 插件可以选择不执行这个命令通过指定 "RULES 0" 在信息模式. 在这种情况下, 如果插件走一个禁止的棋步, 浅红将呼叫棋局一个丧失. (丧失是不太好的, 所有插件应该支持这个命令如果可能.)

命令	BGTHINK <ON\|OFF>
响应	OK [文本] ERROR [文本]
描述	这个命令通知插件改变后台思考开或关. 浅红不让后台思考当两个插件互相下棋或当用户手动禁止它时. (浅红将总是通知插件转换后台思考开或关在每一个棋局开始时.) 如果插件不支持后台思考 (象指定通过 "BGTHINK 0" 在信息模式, 它不需要支持这个命令.

命令	TIMEOUT
响应	(无)
描述	这个命令被浅红发送在用户指定的时间限制已到而 AI 或 HINTS 命令还没有结束时. 这个命令与 ABORT 命令相似. 实际上, 唯一不同的是 AI必须停止思考并转到一个有效的棋步或提示列出代替给出 ABORTED 响应. 像用 ABORT 命令一样, 唯一的响应是来自一个未决的 AI 或 HINTS 命令. (插件必须不发出响应如果 AI 是空闲的.) 插件应该选择不执行这个命令通过指定 "TIMEOUT 0" 在信息模式.

浅红象棋 插件说明

浅红象棋插件说明