2. Plugin Modes
Plugins are run in one of two modes, as specified by a command-line parameter:
"-info" and "-plugin". The info mode is used during Qianhong startup.
It allows Qianhong to query the plugin for a description of its capabilities.
The plugin mode is used to actually play a game of Xiangqi.
Info Mode
When the plugin is run with a "-info" argument, all it has to do is print a standard
list of information and exit. The information is of the format:
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
Take the info from QHPlugin.exe as an example (you can see
this yourself by running "<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 The first line is the plugin protocol version. It should read "QHPLUGIN V1.3" (though V1.2 is still supported). The version number allows for future expansion.
AI Engine Name The second line gives the AI engine name that appears in the game.
You'll want to keep it short because the player name boxes are not very big...
Levels The third line tells how many different AI levels the plugin has.
The subsequent lines list each level, one per line, with the number and any additional
text you want to use for description. Levels must be designated by a number. The extra
text (preceded by a space) is optional.
Undo This tells Qianhong whether the UNDO command is supported.
Use 0 for no, 1 for yes.
Hints This tells Qianhong whether the HINTS command is supported.
Use 0 for no, 1 for yes.
Rules This tells Qianhong whether the BAN command is supported.
Use 0 for no, 1 for yes.
BGThink This tells Qianhong whether the BGTHINK command is supported.
Use 0 for no, 1 for yes.
Timeout This tells Qianhong whether the TIMEOUT command is supported.
Use 0 for no, 1 for yes.
Additional Info Following the hints line, all lines up to the ENDINFO line are
treated as additional info that appears in the "Choose AI Engine" dialog box. Blank lines
may be used for formatting.
Plugin Mode
When the plugin is run with a "-plugin [debug]" argument, it is to play a game.
Qianhong redirects STDIN and STDOUT to pipes so it can communicate with the plugin.
The plugin reads commands from STDIN, takes appropriate action, and writes responses
to STDOUT. All commands (except one, but you'll see that later) require a response.
The plugin must flush STDOUT each time it finishes writing a response so that the
data will be sent through the pipe. Failure to flush the stream will cause Qianhong
to wait indefinitely for the data.
The optional "debug" argument is used when Qianhong is run in plugin debugging mode.
(Run Qianhong with "plugin_debug" as the first argument.) In this mode, the plugin will
have a console and may output anything it wants to the console by writing to STDERR.
Of course, you can also write to a file (or something else) if you like. The debug mode
is for your own benefit; use it as you see fit.
The next section, 3. Commands, describes the
commands and their associated responses.
|
