Qianhong

Chinese Chess for Windows

3. Plugin Commands

Qianhong sends the following commands to the plugins. Each command is discussed in detail below. Command and response words are in ALL CAPS, though your plugin may choose to recognize lower-case commands as well. 

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

  Optional:
    UNDO
    HINTS
    BAN <count> ...
    BGTHINK <ON|OFF>
    TIMEOUT

A note on responses: All responses must end with a newline character ('\n'). Expected responses vary by command, but the two most common responses are OK and ERROR. Both of these may be followed (on the same line) by additional text as desired. Errors will usually be reported in a Qianhong message box, in which case the user will be able to read the text description of the error.

LEVEL
CommandLEVEL
Response<current-level>
DescriptionFor a LEVEL command with no parameter, reply with the current level number.
CommandLEVEL <new-level>
ResponsesOK [text]
ERROR [text]
DescriptionFor a LEVEL command with a parameter, set the current level to the one specified by the given number. Reply OK if successful, or ERROR if the number is out of range.

FEN
CommandFEN <FEN-string>
ResponsesOK [text]
ERROR [text]
DescriptionThis command instructs the plugin to set the board using the FEN string (see www.wxf.org/xq/computer/fen.pdf for details on FEN for Chinese Chess). Red will always be on the bottom (i.e. the last line of the string). Reply OK if the board is set, or ERROR if something goes wrong.

PLAY
CommandPLAY <ICCS-move>
ResponsesOK [text]
ERROR [text]
DescriptionThis tells the plugin to play the given move. The move parameter is in ICCS notation of the form "A0-A1". Looking down on a board with red on the bottom, A0 is the lower-left corner (where red's left chariot starts) and I9 is the upper-right corner (where black's left chariot starts). So the move "A0-A1" would move the piece in the near corner of red's ninth file up one spot. (See notation conventions in 4. Tricky Stuff for more.) Reply OK if the move is made, or ERROR if something goes wrong.

LOAD
CommandLOAD <count> \n [ICCS-move \n] ...
ResponsesOK [text]
ERROR [text]
DescriptionTells the plugin to play a list of moves. This allows Qianhong to load a whole sequence of moves much quicker than using multiple PLAY commands. The parameter is the number of moves, which are given in ICCS format, one-per-line, following the LOAD command.

AI
CommandAI
Responses<ICCS-move>
ERROR [text]
ABORTED
DescriptionTells the plugin to move for the current player and report the move. The plugin responds with the move in ICCS notation of the form "A0-A1", or ERROR if something goes wrong. If the plugin's AI engine takes more than a second to respond, the plugin must keep watching STDIN for new commands, and interrupt the AI engine if a command comes before the engine is done thinking. In this case, the plugin should respond with ABORTED, then process the next command as normal.

Qianhong typically only aborts the AI command when the user closes the app or quits the current game. The exception is with the TIMEOUT command, which, if supported, is sent to cause the AI to stop thinking and reply with the best move it has come up with so far.

ABORT
CommandABORT
Response(none)
DescriptionThe ABORT command is used when an AI or HINTS command is in progress and Qianhong needs to cancel it and get the plugin back to a ready state. Since the plugin must abort AI and HINTS commands when any new command is sent, this is just a way to stop the AI engine without causing a new command to execute. The plugin does not reply to the ABORT command directly; the only response is from a terminated AI or HINTS command that responds with ABORTED.

QUIT
CommandQUIT
ResponseBYE
DescriptionThis command tells the plugin to stop running and exit. The plugin responds with BYE when it shuts down. (If the plugin doesn't respond or close, Qianhong will give it about a second and then kill it. This is a last resort that may leave resources open, so the plugin should be sure to shut down gracefully when it is told to quit.)

UNDO
CommandUNDO
ResponsesOK [text]
ERROR [text]
DescriptionTells the plugin to undo the last move. The plugin responds with OK if it can undo it, or ERROR if something goes wrong (or if no moves have been played yet).

The plugin may choose not to implement this command (to the dismay of users =) by specifying "UNDO 0" in the info mode.

HINTS
CommandHINTS
Responses <hint [description]> \n [hint [description] \n] ... ENDHINTS
ERROR [text]
ABORTED
DescriptionRequests hints on the current move from the plugin. This is basically the same as the AI command except that: (1) the plugin does not play a move, (2) the plugin may suggest more than one move, and (3) the plugin may describe the move(s) to the user.

The nominal response is one or more ICCS moves, one per line, followed by a line that says ENDHINTS. Moves should be listed in order from best to worst; illegal moves must not be listed. Each ICCS move may be followed (on the same line) by additional text describing the move. Other responses are ERROR and ABORTED. (Since this command may take more than a second to execute, it should be interruptible by ABORT and TIMEOUT--see the AI command for more.)

The plugin may choose not to implement this command (to the dismay of users =) by specifying "HINTS 0" in the info mode.

BAN
CommandBAN <count> \n [ICCS-move \n] ...
ResponsesOK [text]
ERROR [text]
DescriptionTells the plugin that the listed moves are considered illegal for the next AI or HINTS command. This allows Qianhong to moderate the game like a referee, and lets the plugins choose alternate moves accordingly. The parameter is the number of banned moves, which are given in ICCS format, one-per-line, following the BAN command.

The plugin may choose not to implement this command by specifying "RULES 0" in the info mode. In this case, if the plugin plays a banned move, Qianhong will call the game a forfeit. (Forfeits are not pretty, so plugins should support this command if at all possible.)

BGTHINK
CommandBGTHINK <ON|OFF>
ResponsesOK [text]
ERROR [text]
DescriptionThis command instructs the plugin to turn its background thinking on or off. Qianhong disables background thinking when two plugins are playing each other or when the user manually disables it. (Qianhong will always tell the plugin to turn BG thinking on or off at the start of each game.)

If the plugin does not support BG thinking (as specified by "BGTHINK 0" in the info mode, it does not need to support this command.

TIMEOUT
CommandTIMEOUT
Responses(none)
DescriptionThis command is sent by Qianhong after the user-specified time limit is up and the AI or HINTS command has not completed. This command similar to the ABORT command. In fact, the only difference is that the AI must stop thinking and return a valid move or hints list instead of giving the ABORTED response. As with the ABORT command, the only response is from a pending AI or HINTS command. (The plugin must not send a response if the AI is idle.)

The plugin may choose not to implement this command by specifying "TIMEOUT 0" in the info mode.

That's it for the commands. If you have questions about them, or if my descriptions are not very clear, there are a few things you can do to better understand the protocol:

  • Look at the source code for keplugin and VsccPlugin for examples.
  • Run Qianhong with the "plugin_debug" parameter and watch the communication with the plugins.
  • Run a plugin directly (with the "-plugin" argument) and type in your commands. (Both QHPlugin.exe and keplugin.exe have a special command, SCR, that displays the game board to help you follow the game when you are running it by hand.)

The next section, 4. Tricky Stuff, describes things you should watch out for when writing your plugin.