淺紅象棋插件說明

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" 在信息模式.

淺紅象棋 插件說明

淺紅象棋插件說明