XQF
象棋演播室(XQStudio) 1.0版XQF文件格式說明
(XQF 1.0)
(過河象, xqstudio@qipaile.net)
2001年4月16日
一、說明
本文件格式是XQStudio 1.0所使用的文件格式，現公佈該格式的主要目的是為了方便程序員將棋譜數據保存為XQF文件格式，以便藉助於XQStudio的打譜功能。各下棋網站或對弈軟件均可將棋譜保存為此格式，這樣XQStudio的任意版本均可以使用該文件。
由於XQStudio 1.0的後續版本使用了更為複雜的文件格式，使用該格式不保證能讀出XQStudio更高版本的XQF文件。換句話說，該格式只保證可以產生一個正確的XQF文件，不保證所有的XQF文件都是該格式。
二、XQF文件使用的棋盤坐標
在XQF文件中，用數字坐標表示棋盤上交叉點的位置，其中X坐標從0到8,Y坐標從0到9，坐標的原點(0,0)在棋盤的左下角。如下圖，黑方的將在位置(4,9)處，紅方的帥在位置(4,0)處。
在XQF文件中，一個棋盤位置用一個字節表示，字節值= X * 10 + Y。因此上圖中的黑帥可用字節值49(十進制)表示，也就是十六進制的0x31；紅方的帥可用字節值40表示，也就是十六進制的0x28。所有被吃掉的子，用位置255,即十六進制的0xFF表示。
三、XQF文件中初始局面的表示
在XQF文件中，使用連續的32個字節表示棋盤的初始局面。這32個字節的位置順序是固定的，含義如下:
01 - 16:依次為紅方的車馬相士帥士相馬車炮砲兵兵兵兵兵
17 - 32:依次為黑方的車馬象士將士像馬車炮炮卒卒卒卒卒
用這32個字節的含義加上前面所說的字節值和棋盤位置的對應關係，可以用連續32個字節的值表示一個當前的局面。例如，全局的初始局面可以用如下的32個字節表
示(注：所有的值為十進制，紅方和黑方均從右到左排列):
(80,70,60,50,40,30,20,10,00,72,12,83,63,43,23,03,09,19,29,39,49,59,69,79,89,17,77,06,26,46,66,86)
四、XQF 1.0文件格式說明
下面的部分是XQF 1.0的文件格式說明，請嚴格按該格式生成XQF文件。下面說明中文件的偏移量用16進製表示。 XQF文件由文件頭和棋譜記錄兩部分組成，分別說明如下：
A.文件頭部(0000 - 03FF)
0000 - 0001 XQF文件標記，必須為'XQ' (0000 = 'X', 0001 = 'Q')
0002 XQF文件版本號，必須為0x0A = (XQF 1.0)。
0003 - 000F保留：必須全部為0x00
0010 - 002F這32個字節是棋局的開局局面，局面說明見“局面表示”
0030 - 0032保留：必須全部為0x00
0033棋局的結果: 0x00-未知,0x01-紅勝,0x02-黑勝,0x03-和棋
0034 - 003F保留：必須全部為0x00
0040棋局的類型: 0x00-全局文件, 0x01-佈局文件, 0x02-中局文件, 0x03-殘局文件
0041 - 004F保留：必須全部為0x00
0050標題的長度(即下面文字的長度，下同)
0051 - 008F標題文字
從0050-008F實際是一個字符串的保存方法，先在第一個 字節保存字符串的長度，接著存字符串的內容，不足的部 分用0x00填充（下同）。
0090 - 00CF保留：必須全部為0x00
00D0比賽名稱的長度
00D1 - 010F比賽名稱
0110比賽日期的長度
0111 - 011F比賽日期
0120比賽地點的長度
0121 - 012F比賽地點
0130紅方棋手名字的長度
0131 - 013F紅方棋手名字
0140黑方棋手名字的長度
0141 - 014F黑方棋手名字
0150用時規則的長度
0151 - 018F用時規則
0190紅方用時的長度
0191 - 019F紅方用時
01A0黑方用時的長度
01A1 - 01AF黑方用時
01B0 - 01CF保留:必須全部為0x00
01D0棋譜講評人名字的長度
01D1 - 01DF棋譜講評人名字
01E0文件作者名字的長度
01E1 - 01EF文件作者名字
01F0 - 03FF保留:全部為0x00
B.棋譜記錄(0400 -文件尾部)
從0x0400開始存放棋譜記錄，每步記錄的存放格式為: 8個棋譜記錄字節+ 0個或多個字節的棋譜註解文本。其中，8個棋譜記錄字節的格式為:
第1字節:本步棋的開始位置坐標的字節值(X*10+Y) + 24 (十進制)。
第2字節:本步棋的到達位置坐標的字節值(X*10+Y) + 32 (十進制)。
第3字節:如果不是最後一步棋，為0xF0；如果是最後一步棋，為0x00。
第4字節:保留:必須為0x00。
第5-8字節:為一個32位整數(x86格式,高字節在後)，表明本步註解的大小，如果沒有註解，則為0x00000000。
如果本步沒有評註，即5-8字節全部為0x00，則本步結束，否則，隨後存放本步評註文本，文本不以'\0'結束(由於前面已經有大小,該文本的長度必須等於5-8字節處的整數值)。如此反复，可將所有棋步存入。 (暫時不支持變著的保存)。從上面可以看出如果沒有註解，一步棋的記錄共佔8個字節。
需要說明的是，在真正的對局記錄開始前，必須有一步空的著法，稱為第0步，該步的第1 - 8字節必須是0x18, 0x20, 0xF0, 0xFF, 0x00, 0x00, 0x00, 0x00。由於這些字節是固定的，所以真正的棋譜記錄是從0x0408處開始的。如果您的棋局只有初始局面而沒有任何著法記錄(即只有一個殘局局勢),則文件中棋譜記錄只有第0步的記錄，並且該記錄的8個字節為:0x18,0x20,0x00,0xFF,0x00,0x00,0x00,0x00。詳細的格式請參見本文後面的文件例子。
四、給程序員
使用上面的格式，可以將全局或殘局的主變著存入XQF文件，也可以編寫XQF文件信息的處理程序，XQF文件信息在各版本中是相同的，並且沒有任何加密措施。
該文件格式的最新版本可到作者的主頁(http://www.qipaile.net)上下載,如有不明白的地方，可以向作者詢問，歡迎大家將文件保存為XQF文件。
過河象(xqstudio@qipaile.net)
2001年4月16日
************************************************************************** * * *最新文件格式的版本請看“http://www.qipaile.net/xqstudio/XqfFormat.txt”* *以上URL請注意字母的大小寫。 * * * **************************************************************************
附: XQF 1.0格式文件的例子(為節省篇幅，只有8個回合的記錄)
A.棋譜文件內容如下:
標題:仙人指路對起馬局
賽事: "中立杯"象棋電視快棋賽
日期: 1997年11月16日
地點:北京
紅方:柳大華
黑方:呂欽
結果:黑方勝
評論:劉殿中
作者:過河象
1.兵七進一馬８進７ 2.兵三進一炮２平３ 3.相七進五馬２進１ 4.馬八進七車１平２ 5.車九平八車２進４ 6.炮八平九車２平８ 7.炮二進五炮３平８ 8.馬二進三車９平８
棋譜由XQStudio生成(http://www.qipaile.net/xqstudio)
B.對應上面棋局的XQF文件內容如下:
請參照前面的說明進行分析。
0000: 58 51 0A 00 00 00 00 00-00 00 00 00 00 00 00 00
'XQ' . -這三個字節是重要的文件標記，不可改變。
0010: 50 46 3C 32 28 1E 14 0A-00 48 0C 53 3F 2B 17 03
0020: 09 13 1D 27 31 3B 45 4F-59 11 4D 06 1A 2E 42 56
以上32個字節為棋局的初始局面的位置，如過您要生成的文件是全局文件，可直接使用上面的數據。
0030: 00 00 00 02 00 00 00 00-00 00 00 00 00 00 00 00
棋局的結果，0x02=黑勝
0040: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
棋局文件的類型: 0x00=全局文件
0050: 10 CF C9 C8 CB D6 B8 C2-B7 B6 D4 C6 F0 C2 ED BE
0060: D6 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
0070: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
0080: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
以上64個字節為文件標題，第一個字節為長度(0x10), “仙人指路對起馬局”共16個字節，所以長度為0x10。
下面所有的字符串規律相同。
0090: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
00A0: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
00B0: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
00C0: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
以上64個字節為保留字節，必須為0x00。
00D0: 16 22 D6 D0 C1 A2 B1 AD-22 CF F3 C6 E5 B5 E7 CA
00E0: D3 BF EC C6 E5 C8 FC 00-00 00 00 00 00 00 00 00
00F0: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
0100: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
以上64個字節為比賽名稱“"中立杯"象棋電視快棋賽”
0110: 0E 31 39 39 37 C4 EA 31-31 D4 C2 31 36 C8 D5 00
以上16個字節為比賽日期“1997年11月16日”
0120: 04 B1 B1 BE A9 00 00 00-00 00 00 00 00 00 00 00
以上16個字節為比賽地點“北京”
0130: 06 C1 F8 B4 F3 BB AA 00-00 00 00 00 00 00 00 00
以上16個字節為紅方棋手“柳大華”
0140: 06 C2 C0 20 20 C7 D5 00-00 00 00 00 00 00 00 00
以上16個字節為黑方棋手“呂欽”
0150: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
0160: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
0170: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
0180: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
以上64個字節為用時規則，空，沒有輸入
0190: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
以上16個字節為紅方用時，空，沒有輸入
01A0: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
以上16個字節為紅方用時，空，沒有輸入
01B0: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
01C0: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
以上64個字節為保留字節，必須為0x00
01D0: 06 C1 F5 B5 EE D6 D0 00-00 00 00 00 00 00 00 00
以上16個字節為棋譜講評“劉殿中”
01E0: 06 B9 FD BA D3 CF F3 00-00 00 00 00 00 00 00 00
以上16個字節為文件作者“過河象”
01F0: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
...為節省篇幅，省去許多0x00 ...
03F0: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00
以上從0x1F0-0x3F0的所有字節為保留字節，為0x00
從下面(0x400)出開始為棋譜記錄
0400: 18 20 F0 FF 00 00 00 00-2F 38 F0 00 00 00 00 00
第0步，內容固定(8字節)第1步:兵七進一
第1步“兵七進一”內容分析如下:
兵七進一的起點坐標(2, 3),落點坐標(2, 4),則
1.起點字節值=(X*10+Y)+24 = 23+24 = 47 (0x2F)
2.落點字節值=(X*10+Y)+32 = 24+32 = 56 (0x38)
3.本步不是最後一步，所以第3個字節為(0xF0)
4.第4個字節是保留字節，必須為0x00 (0x00)
5.本步沒有註解，所以5-8字節為0x00. (0x00)
6. (0x00)
7. (0x00)
8. (0x00)
如果棋譜記錄中沒有任何著法，則只有第0步的棋譜記錄，並且第0步棋譜記錄的第三個字節為0x00,文件內容到0x0407處就結束了。
0410: 67 63 F0 00 00 00 00 00-57 60 F0 00 00 00 00 00
馬８進７兵三進一
0420: 29 3B F0 00 00 00 00 00-2C 4A F0 00 00 00 00 00
炮２平３相七進五
0430: 2B 27 F0 00 00 00 00 00-22 36 F0 00 00 00 00 00
馬２進１馬八進七
0440: 21 33 F0 00 00 00 00 00-18 2A F0 00 00 00 00 00
車１平２車九平八
0450: 2B 2F F0 00 00 00 00 00-24 22 F0 00 00 00 00 00
車２進４炮八平九
0460: 27 6B F0 00 00 00 00 00-60 6D F0 00 00 00 00 00
車２平８炮二進五
0470: 33 6D F0 00 00 00 00 00-5E 5E F0 00 00 00 00 00
炮３平８馬二進三
0480: 71 6F 00 00 00 00 00 00
車９平８ (注意第3個字節，最後一步,應為0x00)
注：
1.如果將上面的全部數據存到一個文件中，即形成一個標準的XQF文件，該文件的大小為0x0488(十進制1160)個字節。
2.為研究和測試XQF 1.0文件結構，可下載XQStudio 1.0的版本生成多個不同的文件進行比較和分析，下載地址: “http://www.qipaile.net/xqstudio/XQStudio_1_0.zip” (注意大小寫)
(☆☆☆歡迎訪問“http://www.qipaile.net” ☆☆☆)
