XQF

From WeWeWeb Wiki
Jump to: navigation, search

象棋演播室(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 coordinates.png

在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)

http://www.qipaile.net

2001年4月16日

************************************************************************** 
* * 
*最新文件格式的版本請看“http://www.qipaile.net/xqstudio/XqfFormat.txt”* 
*以上URL請注意字母的大小寫。 * 
* * 
************************************************************************** 


附: XQF 1.0格式文件的例子(為節省篇幅,只有8個回合的記錄)

A.棋譜文件內容如下:


標題:仙人指路對起馬局

賽事: "中立杯"象棋電視快棋賽

日期: 1997年11月16日

地點:北京

紅方:柳大華

黑方:呂欽

結果:黑方勝

評論:劉殿中

作者:過河象


1.兵七進一馬8進7 2.兵三進一炮2平3 

3.相七進五馬2進1 4.馬八進七車1平2 

5.車九平八車2進4 6.炮八平九車2平8 

7.炮二進五炮3平8 8.馬二進三車9平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


馬8進7兵三進一

0420: 29 3B F0 00 00 00 00 00-2C 4A F0 00 00 00 00 00


炮2平3相七進五

0430: 2B 27 F0 00 00 00 00 00-22 36 F0 00 00 00 00 00


馬2進1馬八進七


0440: 21 33 F0 00 00 00 00 00-18 2A F0 00 00 00 00 00


車1平2車九平八

0450: 2B 2F F0 00 00 00 00 00-24 22 F0 00 00 00 00 00


車2進4炮八平九

0460: 27 6B F0 00 00 00 00 00-60 6D F0 00 00 00 00 00


車2平8炮二進五

0470: 33 6D F0 00 00 00 00 00-5E 5E F0 00 00 00 00 00


炮3平8馬二進三

0480: 71 6F 00 00 00 00 00 00


車9平8 (注意第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” ☆☆☆)