This document describes communication between a brain (an artificial intelligence) and a go-moku manager (a program which manages and controls a tournament). The manager creates two pipes. The first pipe is used to send commands from the manager to the brain. The second pipe is used to send replies from the brain to the manager. The brain uses standard input-output functions (scanf and printf in C, readln and writeln in Pascal,...) therefore it can be written in any programming language. The brain must be a console application, not Windows GUI. Be careful, some run-time libraries buffer the console output. For example, it is necessary to call fflush(stdout) after printf in C programs. You can also use low-level functions ReadFile and WriteFile.
Each line contains exactly one command (there is only one exception). The manager puts bytes CR LF (0x0d, 0x0a) at the end of lines. The brain can send lines that are ended with CR LF, or just LF, or CR. The manager ignores lines that are empty. It must not crash if a line is too long, but it can silently cut very long lines.
If the brain has only one thread, it is very important not to read from input when the brain is required to think or respond to a command. It would lead to deadlock (both brain and manager are waiting). Manager will terminate the brain in this situation after the time for a turn is out. The brain can have two threads to avoid that problem. The first thread reads commands from input and the second thread thinks and writes responds to output. It is necessary to use some synchronization objects (events, locks or semaphores). The number of threads is not important for a tournament. One thread is sufficient for a tournament. But two threads are useful for human players. For example, someone may want to change time limits while the brain already started to think. The thinking can also be easily canceled at any time without terminating the brain.
The brain is required to process commands START, BEGIN, INFO, BOARD, TURN, END. The brain can ignore INFO commands which are not needed. The reply for every other command is UNKNOWN (Due to backward compatibility and possibility to extend the protocol).
Example: pbrain-swine.exe pbrain-pisq5.exeOnly the executable file is required to begin with prefix "pbrain-". The name of ZIP file does not have this prefix.
Working directory is set by the manager. It doesn't have to be the directory where the brain's executable file is saved. The brain must specify full path to all data files which it uses. It can obtain the path from function GetModuleFileName or it can look at the beginning of its command line which can be discovered from the main function parameters. The manager must put name of brain's exe file on the command line in such a form so that the brain can open the file.
The brain can create a folder in the current directory to store its temporary files. The name of the folder must be the same as the name of the brain. The maximal allowed size of the folder will be announced on Gomocup web page (it is now 20MB). The manager can delete all temporary files when the manager exits or after a tournament finished. Command INFO folder is used to determine folder where persistent files can be saved.
Example: The manager sends: START 20 The brain answers: OK - everything is good ERROR message - unsupported size or other error
Expected answer: two comma-separated numbers - coordinates of the brain's move Example: The manager sends: TURN 10,10 The brain answers: 11,10
Expected answer: two numbers separated by comma - coordinates of the brain's move Example: The manager sends: BEGIN The brain answers: 10,10
After this command the data forming the playing field are send. Every line is in the form:
[X],[Y],[field]where [X] and [Y] are coordinates and [field] is either number 1 (own stone) or number 2 (opponent's stone) or number 3 (winning line when continuous game rule is on). The manager should send these lines in the same order as moves were made, but the brain should not depend on it and must cope with any order. Data are ended by DONE command. Then the brain is expected to answer such as to TURN or BEGIN command.
Example: The manager sends: BOARD 10,10,1 10,11,2 11,11,1 9,10,2 DONE The brain answers: 9,9
The key can be: timeout_turn - time limit for each move (milliseconds, 0=play as fast as possible) timeout_match - time limit of a whole match (milliseconds, 0=no limit) max_memory - memory limit (bytes, 0=no limit) time_left - remaining time limit of a whole match (milliseconds) game_type - 0=opponent is human, 1=opponent is brain, 2=tournament, 3=network tournament rule - 0=five or more stones in a row win, 1=exactly five in a row win, 2=continuous game, 3=continuous and exactly five evaluate - coordinates X,Y representing current position of the mouse cursor folder - folder for persistent filesInformation about time and memory limits is sent before the first move (after or before START command). Info time_left is sent before every move (before commands TURN, BEGIN and BOARD). The remaining time can be negative when the brain runs out of time. Remaining time is equal to 2147483647 if the time for a whole match is unlimited. The manager is required to send info time_left if the time is limited, so that the brain can ignore info timeout_match and only rely on info time_left.
Time for a match is measured from creating a process to the end of a game (but not during opponent's turn). Time for a turn includes processing of all commands except initialization (commands START, RECTSTART, RESTART). Turn limit equal to zero means that the brain should play as fast as possibble (eg count only a static evaluation and don't search possibble moves).
INFO folder is used to determine a folder for files that are permanent. Because this folder is common for all brains and maybe other applications, the brain must create its own subfolder which name must be the same as the name of the brain. If the manager does not send INFO folder, then the brain cannot store permanent files.
Only debug versions should respond to INFO evaluate. For example, it can print evaluation of the square to some window. It cannot be written to the standard output. Release versions should just ignore INFO evaluate.
How should the brain behave when obtains unknown INFO command ?
- Ignore it, it is probably not important. If it was important, it is not in an INFO command form.
How should behave the brain obtaining the unachievable INFO command?
(for example too small memory limit)
- The brain should wait with the output of the problem until the manager sends the first command not having an INFO form (TURN, BOARD or BEGIN). The manager does not read messages from the brain when sending INFO command.
Example: INFO timeout_match 300000 INFO timeout_turn 10000 INFO max_memory 83886080 Expected answer: none
Expected answer: none The brain should delete its temporary files.
Example: The manager sends: ABOUT The brain answers: name="SomeBrain", version="1.0", author="Nymand", country="USA"
Example: The manager sends: RECTSTART 30,20 The brain answers: OK - parameters are good ERROR message - rectangular board is not supported or other error
Example: The manager sends: RESTART The brain answers: OK
Example: The manager sends: TAKEBACK 9,10 The brain answers: OK
Expected answer: two comma-separated numbers which should be the same as PLAY parameters. If the brain doesn't like the coordinates sent by the manager, it can answer some other coordinates (but it is not recommended). Example: The brain has sent: SUGGEST 10,10 The manager sends: PLAY 12,10 The brain moves onto 12,10 and answers: 12,10
It is recommended to send only English messages. If the brain chooses another language, it should detect code page that is used on the PC (Win32 function GetACP()) and should not send messages that cannot be displayed in that code page.
Example: The manager sends: TURN 10,15 The brain answers: DEBUG The most promising move now is [10,14] alfa=10025 beta=8641 DEBUG The most promising move now is [11,14] alfa=10125 beta=8641 MESSAGE I will be the winner 10,16