Fox Go AI Protocol
Version：1.05
Date：2022-06-06
Company：Beijing Wild Fox Century Technology Co., Ltd
Home Page：https://www.foxwq.com
Email: [email protected]
Version History：
Date Version Editor Description
20161026 1.00 Zhang Weifang Initial version.
20161206 1.01 Zhang Weifang Increases rules and time messages.
20161207 1.02 Zhang Weifang Complete description. Increase the official email.
20161230 1.03 Zhang Weifang Added Calculated Score related commands
20180516 1.04 Zhang Weifang Delete some irrelevant content.
20220606 1.05 Zhang Weifang Modify the official website URL.
1 / 9
1 Communication Model
FOX TCP AI
This Protocol
Controller GTP
Client Engine
The Fox Go client does not support the GTP protocol to communicate directly with the AI
engine. It must be through a controller for transit. The Fox Go client connects to the controller
through TCP and uses this protocol to communicate with the controller.
In order to facilitate the description described later, the text referred to as Controller AI, the
text appears in all AI refers to the Controller. FOX appears in the text refers to the Fox Go client.
Note: It is recommended to use the FoxGTP program provided by Fox Go.
2 Interaction
2.1 Initial Status Notice
2.1.1 Non-game State
When connected to the AI in a non-game state, the $FASTATUS command gives the current
nog-game state.
2.1.2 Game State
When connected to the AI in game state:
◼ The current game rule is given by the $FARULE command.
◼ The $FASTATUS command gives the current state of the game, including the AI color of
the player, the current move sequence information.
◼ The $FATIMELEFT command gives the current game remaining time information.
◼ The $FAMOVE command gives the last move information.
2 / 9
2.1.3 The New Game Starts
In the case of connected AI, when the new game starts:
◼ The current game rule is given by the $FARULE command.
◼ The $FASTATUS command gives the current state of the game, including the AI color of
the player, no move sequence information.
◼ The $FATIMELEFT command gives the current game remaining time information.
◼ The $FAMOVE command gives the last move information. It is only used to indicate
whether or not it is the turn of the AI.
2.2 Move Information Notice
When in the game state, the $FAMOVE command gives the last move, including whether it is
AI turn, the color of AI, and the move information(index, coordinates, color).
If the current turn to AI play, AI need to use the command $AFPLAY notify FOX to put stone,
or use the command $AFSKIP notify FOX to pass.
Use the $AFGIVEUP command to give up, regardless of whether the AI is currently in turn.
2.3 Pass Information Notice
When in the game state, the $FASKIP command gives pass information, including whether it
is AI turn, and the color of AI.
If the current turn to AI play, AI need to use the command $AFPLAY notify FOX to put stone,
or use the command $AFSKIP notify FOX to pass.
Use the $AFGIVEUP command to give up, regardless of whether the AI is currently in turn.
2.4 Remaining Time Notice
When in the game state, the remaining time information of the current game is given by the
$FATIMELEFT command when the main time elapses or the remaining number of Byo yomi times
decreases.
2.5 Result Information Notice
When the game ends, the $FARESULT command gives the current game result information.
2.6 AI Play
When the AI receives $FAMOVE or $FASKIP, if the state is the current turn to AI, you can use
the command $AFPLAY for playing stone, the command must contain the color of AI, and the
3 / 9
move information.
2.7 AI Pass
When the AI receives $FAMOVE or $FASKIP, if the state is the current turn to AI, you can use
the command $AFSKIP for passing, the command must contain the color of AI.
2.8 AI Give Up
When in the game state, at any time AI can use the $AFGIVEUP command to give up, the
command must contain the color of AI.
2.9 AI Request Status
When in the game state, at any time AI can use the $AFSTATUS command to query the current
state of the game, the command must contain the color of AI.
2.10 AI calculated scores
Use the command $FASCORE to request a calculated score from the AI. The AI gives the
calculated score using the command $AFSCORE.
3 Communication Protocol
3.1 Packet Format
The packet format is as follows(see GPS):
$ABXXXX ,ddd … ,ddd *hh <CR><LF>
Format Description:
◼ The packet begins with $, followed by the packet command character, ending with
<CR><LF>.<CR> refers to the carriage return value of ‘\r’, <LF> refers to
a newline value of ‘\n’.
◼ *hh before <CR><LF> is the check byte. * is a fixed symbol. hh is
hexadecimal character (not case-insensitive). The value of hh is the
exclusive OR of all characters between $ and * (excluding the characters
$ and *)(see Appendix A for checksum C++ code).
◼ The contents of the packet are separated by commas (,). There is no limit to the number of
content items in a packet. Content items need to be resolved according to specific commands.
4 / 9
3.2 Commands
Command Description Version
$FASTATUS F0X->AI Notifies AI of current game state 1.00
$FAMOVE FOX->AI Notifies AI of current move information 1.00
$FASKIP FOX->AI Notifies AI of current pass information 1.00
$FARESULT FOX->AI Notifies AI of current game result 1.00
$AFPLAY AI->FOX Notify FOX put stone 1.00
$AFSTATUS AI->FOX Notify FOX query the state of the game 1.00
$AFSKIP AI->FOX Notify FOX that AI pass 1.00
$AFGIVEUP AI->FOX Notify FOX that AI give up 1.00
$FARULE F0X->AI Notifies AI of the current game rule 1.01
$FATIMELEFT F0X->AI Notifies AI of the current time remaining 1.01
$FASCORE FOX->AI The AI is requested to calculate the score 1.03
$AFSCORE AI->FOX Notify FOX AI calculated score results 1.03
3.2.1 $FASTATUS (FOX->AI)
Description: F0X->AI Notifies AI of current game state
Format: $FASTATUS,1,W,1^12^11^B,2^13^12^W,...,n^xx^yy^s*hh<CR><LF>
Analysis:
⚫ $FASTATUS is the name of the command.
⚫ The content item 1 indicates whether the game is currently in play, 0 indicates non-game, 1
indicates that the game is playing, and if it is 0, there is no subsequent content item.
⚫ The content item 2 represents the current AI color, B represents Black, W represents White.
⚫ The content item 3 and the subsequent content items represent the move sequence. Move
format is n^xx^yy^s. n is the index of move (starting from 1), xx is the X coordinate (from left
to right is X positive direction, the value is 0-18 in 19x19), yy is the Y coordinate (from top to
bottom is Y positive direction, the value is 0-18 in 19x19), s represents the stone color (W or
B).
5 / 9
3.2.2 $FAMOVE (FOX->AI)
Description: FOX->AI Notifies AI of current move information
Format: $FAMOVE,1,W,1^12^11^B*hh<CR><LF>
Analysis:
⚫ $FAMOVE is the name of the command.
⚫ The content item 1 indicates whether or not it is the turn of the AI, 1 indicates the turn of the
AI, 0 indicates the turn of the opponent.
⚫ The content item 2 represents the current AI color, B represents Black, W represents White.
⚫ The content item 3 indicates the move information, if the board without a stone is 0^0^0^N,
the command only indicates whether the current turn to AI.
3.2.3 $FASKIP (FOX->AI)
Description: FOX->AI Notifies AI of current pass information
Format: $FASKIP,0,W*hh<CR><LF>
Analysis:
⚫ $FASKIP is the name of the command.
⚫ The content item 1 indicates whether or not it is the turn of the AI, 1 indicates the turn of the
AI, 0 indicates the turn of the opponent. Can be based on the flag to determine whether the
pass is the opponent or AI.
⚫ The content item 2 represents the current AI color, B represents Black, W represents White.
3.2.4 $FARESULT (FOX->AI)
Description: FOX->AI Notifies AI of current game result
Format: $FARESULT,W+350*hh<CR><LF> White 3.5 wins
$FARESULT,W+R*hh<CR><LF> White wins
$FARESULT,0*hh<CR><LF> Draw
Analysis:
⚫ $FARESULT is the name of the command.
⚫ The content item 1 is 0 to indicate a draw.
⚫ The content item 1 is W(B)+ format indicates that it is not a draw game. W means White wins,
B means Black wins, +350 means 3.5 wins, and +R means mid-win.
3.2.5 $AFPLAY (AI->FOX)
Description: AI->FOX Notify FOX put stone
Format: $AFPLAY,B,1^12^11^B*hh<CR><LF>
Analysis:
⚫ $AFPLAY is the name of the command.
6 / 9
⚫ The content item 1 represents the current AI color, B represents Black, W represents White.
⚫ The content item 2 indicates the move information (see content item 3 of the $FASTATUS
command). The move information must contain the correct index. The index value is the last
move index plus 1.
3.2.6 $AFSTATUS (AI->FOX)
Description: AI->FOX Notify FOX query the state of the game. the results will be reported to AI by
$FASTATUS command.
Format: $AFSTATUS,W*hh<CR><LF>
Analysis:
⚫ $AFSTATUS is the name of the command.
⚫ The content item 1 represents the current AI color, B represents Black, W represents White.
3.2.7 $AFSKIP (AI->FOX)
Description: AI->FOX Notify FOX that AI pass
Format: $AFSKIP,W*hh<CR><LF>
Analysis:
⚫ $AFSKIP is the name of the command.
⚫ The content item 1 represents the current AI color, B represents Black, W represents White.
3.2.8 $AFGIVEUP (AI->FOX)
Description: AI->FOX Notify FOX that AI give up
Format: $AFGIVEUP,W*hh<CR><LF>
Analysis:
⚫ $AFGIVEUP is the name of the command.
⚫ The content item 1 represents the current AI color, B represents Black, W represents White.
3.2.9 $FARULE (FOX->AI)
Description: F0X->AI Notifies AI of the current game rule
Format: $FARULE,19,60,30,5,650,n^xx^yy^s,...,n^xx^yy^s*hh<CR><LF>
Analysis:
⚫ $FARULE is the name of the command.
⚫ The content item 1 indicates board size, such as 19, 13.
⚫ The content item 2 represents the main time in seconds.
⚫ The content item 3 represents the byo yomi time in seconds.
⚫ The content item 4 represents the byo yomi count.
⚫ The content item 5 represents the komi, 650 represents 6.5.
7 / 9
⚫ The content item 6 and subsequent content item represent handicap move sequence. The
format of the move is described in content item 3 of the $FASTATUS command. Here the index
in the moves is 0 and the stone color is B.
3.2.10 $FATIMELEFT (FOX->AI)
Description: F0X->AI Notifies AI of the current time remaining
Format: $FATIMELEFT,60,30,5*hh<CR><LF>
Analysis:
⚫ $FATIMELEFT is the name of the command.
⚫ The content item 1 indicates the remaining main time, and the value goes to zero during the
byo yomi phase.
⚫ The content item 2 represents the byo yomi time, which is the same as the rule and does not
change.
⚫ The content item 3 indicates the remaining byo yomi counts.
3.2.11 $FASCORE (FOX->AI)
Description: F0X->AI The AI is requested to calculate the score
Format: $FASCORE,0*hh<CR><LF>
Analysis:
⚫ $FASCORE is the name of the command.
⚫ The content item 1 indicates whether or not the opponent applies for a calculated score, 1
indicates an opponent, 0 indicates one’s own.
3.2.12 $AFSCORE (AI->FOX)
Description: AI->FOX Notify FOX AI calculated score results
Format: $AFSCORE,0,W+350*hh<CR><LF>
$AFSCORE,1,0*hh<CR><LF>
$AFSCORE,0,error*hh<CR><LF>
Analysis:
⚫ $AFSCORE is the name of the command.
⚫ The content item 1 indicates whether or not the opponent applies for a calculated score, 1
indicates an opponent, 0 indicates one’s own.
⚫ The content item 2 is “error” to indicate AI does not support this command or can not
currently calculate the score.
⚫ The content item 2 is 0 to indicate a draw
⚫ The content item 2 is W(B)+ format indicates that it is not a draw game. W means White wins,
B means Black wins, +350 means 3.5 wins.
8 / 9
Appendix A
Checksum C++ code:
BOOL FOXPKG_CalCheckSum(
IN const BYTE *pDataBuf, // 数据缓冲区
IN DWORD dwcbBufSize, // 缓冲区字节大小
OUT BYTE &byteCheckSum // 带出校验和
)
{
// 参数有效性
if (pDataBuf==NULL || dwcbBufSize==0)
{
return FALSE;
}
// 计算异或和的值
BYTE checkSum = pDataBuf[0];
for (DWORD i=1; i<dwcbBufSize; i++)
{
checkSum ^= pDataBuf[i];
}
// 输出结果
byteCheckSum = checkSum;
return TRUE;
}
9 / 9
