簡介面向想深入研究《夢幻古龍》游戲數(shù)據(jù)格式與資源管理的開發(fā)者這份源代碼包聚焦 GDF 文件的解包、打包與流式讀寫適合具備 C 與面向?qū)ο蠡A(chǔ)、希望理解游戲資源壓縮存儲(chǔ)機(jī)制的讀者參考。壓縮包共 8 個(gè)文件由 5 個(gè)頭文件和 3 個(gè) cpp 源文件組成整體約 21KB涵蓋文件對(duì)象封裝、批量資源管理及數(shù)據(jù)流處理等核心模塊便于按類梳理接口與調(diào)用關(guān)系。已有 585 人學(xué)習(xí)說明該主題在游戲資源修改與工具開發(fā)圈中具備一定關(guān)注度。通過閱讀可實(shí)現(xiàn)單個(gè) GDF 文件的打開、數(shù)據(jù)塊讀取與解壓也能借助管理類完成多文件批量處理并從中體會(huì)壓縮算法與 I/O 設(shè)計(jì)的結(jié)合方式代碼未附圖形界面更適合作為二次開發(fā)與自制解包工具的基礎(chǔ)素材。1. 一個(gè)幾百 MB 的資源包為什么不能直接改里面的圖拿到夢幻古龍的客戶端資源目錄里躺著一堆.gdf貼圖、模型、配置表、腳本全被塞進(jìn)同一個(gè)文件文件名躲在索引里數(shù)據(jù)區(qū)是壓縮過的二進(jìn)制。想換一張 UI 圖或者改一條數(shù)值在十六進(jìn)制編輯器里動(dòng)一個(gè)字節(jié)后面所有偏移就全錯(cuò)位客戶端輕則白屏重則閃退。GDF 文件資源解包打包這套源碼要解決的就是這件事按索引把 GDF 解包成正常的目錄樹改完再按原格式打包回去客戶端照樣認(rèn)。適合做資源替換、界面漢化、數(shù)值調(diào)試、格式研究的人也適合想弄明白“打包文件到底怎么組織”的初學(xué)者。門檻不高會(huì)一點(diǎn) Python、能看懂struct和文件偏移就行。2. 摸清 GDF 的三段式結(jié)構(gòu)文件頭、索引表、數(shù)據(jù)區(qū)在寫循環(huán)之前先干一件看起來很笨但省時(shí)間的事把.gdf拖進(jìn) HxD 或者 010 Editor看前 64 個(gè)字節(jié)。GDF 這類打包格式絕大多數(shù)是同一個(gè)套路——定長文件頭、變長索引表、連續(xù)數(shù)據(jù)區(qū)三段首尾相接。你把這三種段的邊界找對(duì)了解包腳本半小時(shí)能跑通邊界找錯(cuò)后面調(diào)一天都是亂碼。我一般會(huì)先看頭部四個(gè)字節(jié)是不是可打印字符再看第 5 到第 8 字節(jié)像不像一個(gè)小整數(shù)版本號(hào)通常是個(gè)位數(shù)到幾十第 9 到第 12 字節(jié)往往是條目數(shù)量緊跟著一個(gè)偏移值指向索引起點(diǎn)。這幾個(gè)數(shù)能對(duì)上格式基本就摸到了。2.1 文件頭里哪幾個(gè)字段必須先確認(rèn)下面這套頭部布局在同類 GDF 資源里出現(xiàn)頻率很高我手上這份源碼也是按它實(shí)現(xiàn)的。字段順序不一定完全一致但四個(gè)核心信息跑不掉魔數(shù)、版本、條目數(shù)、索引偏移。偏移長度字段說明0x004magic常見為GDF\0或GDF1用來快速識(shí)別格式0x044version版本號(hào)決定索引項(xiàng)是否帶額外字段0x084count文件條目總數(shù)0x0C4index_offset索引表在文件中的起始位置先用一段最小的代碼把頭部讀出來確認(rèn)字段是否講得通import struct # 小端序魔數(shù)4字節(jié)、版本4字節(jié)、條目數(shù)4字節(jié)、索引偏移4字節(jié) HEADER_FMT 4sIII HEADER_SIZE struct.calcsize(HEADER_FMT) # 16 def peek_header(path): with open(path, rb) as f: raw f.read(HEADER_SIZE) magic, version, count, index_off struct.unpack(HEADER_FMT, raw) print(magic , magic) print(version , version) print(count , count) print(index_offset , index_off) return magic, version, count, index_off peek_header(sample.gdf)如果打印出來的count是幾萬甚至上百萬或者index_offset大于文件本身大小說明字段順序或者字節(jié)序不對(duì)先把換成再試一次。大端序在老資源里不是沒有。這里的每個(gè)常量都不是拍腦袋定的HEADER_FMT一旦確認(rèn)下來后面解包和打包必須共用同一份定義不要在兩處各寫一遍改了一處忘了另一處是最常見的事故來源。2.2 索引項(xiàng)是變長的文件名長度決定了怎么跳索引表不是定長數(shù)組絕大部分 GDF 的索引項(xiàng)是“長度 內(nèi)容”的變長結(jié)構(gòu)先一個(gè) 2 字節(jié)的文件名長度接著是文件名本身然后是數(shù)據(jù)偏移、壓縮后大小、原始大小、壓縮標(biāo)志。因?yàn)槲募L度不固定你不能用count * 固定長度去算索引總長只能一條一條順序讀。# 索引項(xiàng)文件名長度(H) 數(shù)據(jù)偏移(I) 壓縮后大小(I) 原始大小(I) 標(biāo)志位(B) ENTRY_FMT HIIIB ENTRY_SIZE struct.calcsize(ENTRY_FMT) # 15這里最容易翻車的是文件名編碼。國產(chǎn)老資源十有八九是 GBK直接decode(utf-8)會(huì)在某個(gè)帶漢字的路徑上拋異常而且往往不是第一條是跑到幾千條的時(shí)候突然炸。穩(wěn)妥寫法是給一個(gè)編碼回退鏈優(yōu)先 GBK失敗再試 UTF-8最后用 latin-1 兜底保證不中斷def decode_name(raw: bytes) - str: for enc in (gbk, utf-8, latin-1): try: return raw.decode(enc) except UnicodeDecodeError: continue return raw.decode(latin-1, errorsreplace)還有一類 GDF 不用變長文件名而是每條索引固定留 64 字節(jié)或 128 字節(jié)的文件名區(qū)不足補(bǔ)\0。這種結(jié)構(gòu)讀起來更簡單但寫回去時(shí)必須把整塊清零再寫否則殘留的舊字符會(huì)串到新文件名后面。判斷方法很直接看索引區(qū)總長度是不是count的整數(shù)倍。2.3 數(shù)據(jù)偏移的基準(zhǔn)點(diǎn)決定了你解出來的是圖還是亂碼索引里那個(gè)偏移值可能是相對(duì)于文件開頭的絕對(duì)偏移也可能是相對(duì)于數(shù)據(jù)區(qū)起點(diǎn)的相對(duì)偏移。這兩種情況在十六進(jìn)制里長得一模一樣但解包結(jié)果天差地別。判斷辦法是拿第一條記錄的偏移和index_offset比一下如果偏移值明顯大于索引起點(diǎn)基本是絕對(duì)偏移如果偏移值從 0 或幾十開始那就是相對(duì)數(shù)據(jù)區(qū)起點(diǎn)的。def resolve_base(first_offset, index_offset, header_size): # 偏移大于索引起點(diǎn)視為絕對(duì)偏移基準(zhǔn)為 0 if first_offset index_offset: return 0 # 否則視為相對(duì)數(shù)據(jù)區(qū)起點(diǎn) return index_offset # 也有格式以 header_size 為基準(zhǔn)需實(shí)測對(duì)齊也值得看一眼。有些包要求每個(gè)文件的數(shù)據(jù)區(qū)起點(diǎn)按 4 字節(jié)或 16 字節(jié)對(duì)齊中間填\0。解包時(shí)對(duì)齊無所謂打包時(shí)不補(bǔ)對(duì)齊客戶端讀出來的貼圖會(huì)花屏——它按對(duì)齊后的偏移去取你少填了幾個(gè)字節(jié)后面全錯(cuò)位。判斷有沒有對(duì)齊看相鄰兩條記錄的offset packed_size和下一個(gè)offset之間有沒有固定的小間隙有就是對(duì)齊填充。3. 解包腳本落地從索引還原出完整目錄樹結(jié)構(gòu)確認(rèn)完解包腳本本身不復(fù)雜核心就三步讀頭、遍歷索引、按偏移取數(shù)據(jù)寫盤。但要把這三步寫扎實(shí)得處理幾個(gè)邊界索引讀完之后文件指針在哪、壓縮標(biāo)志為 0 時(shí)要不要跳過解壓、路徑里帶..或者絕對(duì)路徑時(shí)怎么清洗。下面這份是能直接跑的實(shí)現(xiàn)把前面確認(rèn)過的常量接進(jìn)去即可。3.1 讀頭部并做一次基本校驗(yàn)校驗(yàn)不是形式主義。資源包被截?cái)唷⑾螺d不完整、或者你拿錯(cuò)了版本都會(huì)在這里暴露而不是等到寫了幾千個(gè)文件之后才發(fā)現(xiàn)全是壞的。import os import struct import zlib HEADER_FMT 4sIII HEADER_SIZE struct.calcsize(HEADER_FMT) ENTRY_FMT HIIIB ENTRY_SIZE struct.calcsize(ENTRY_FMT) def read_header(f): raw f.read(HEADER_SIZE) if len(raw) ! HEADER_SIZE: raise ValueError(文件頭不完整可能被截?cái)? magic, version, count, index_off struct.unpack(HEADER_FMT, raw) if magic[:3] ! bGDF: raise ValueError(f魔數(shù)不匹配: {magic!r}) return version, count, index_offmagic[:3] ! bGDF這里只比前三個(gè)字節(jié)是因?yàn)榈谒奈辉诓煌姹纠锟赡苁荺0、1、2。如果你手上的包魔數(shù)完全不是這幾個(gè)字符那就把這行判斷去掉改成打印出來人工確認(rèn)別硬套。3.2 遍歷索引逐條讀出元信息索引區(qū)一次性讀進(jìn)內(nèi)存比逐條seek快得多幾萬條記錄的索引通常也就幾 MB。讀進(jìn)來之后用一個(gè)游標(biāo)pos往前走每次讀完固定部分再按name_len跳過文件名。def read_index(f, count, index_off): f.seek(index_off) buf f.read() entries [] pos 0 for _ in range(count): name_len, offset, packed_size, raw_size, flag struct.unpack_from( ENTRY_FMT, buf, pos ) pos ENTRY_SIZE name decode_name(buf[pos:pos name_len]) pos name_len entries.append({ name: name, offset: offset, packed_size: packed_size, raw_size: raw_size, flag: flag, }) return entriespacked_size和raw_size的關(guān)系能幫你判斷壓縮標(biāo)志是否可信兩者相等時(shí)大概率沒壓縮packed_size明顯小于raw_size才是壓縮過的。有些包的flag字段根本不準(zhǔn)這時(shí)候以大小關(guān)系為準(zhǔn)更穩(wěn)。3.3 寫盤路徑清洗、目錄創(chuàng)建、重名處理寫盤這一步看著簡單坑都在路徑上。資源包里可能混著\和/兩種分隔符可能有大小寫只差一個(gè)字母的兩個(gè)文件在 Windows 上會(huì)互相覆蓋也可能有..這種試圖跳出輸出目錄的路徑。統(tǒng)一處理成/、按段拆分、過濾掉..和空段是必須做的。def safe_join(out_dir, name): parts [p for p in name.replace(\\, /).split(/) if p and p ! ..] return os.path.join(out_dir, *parts) def unpack(src_path, out_dir): with open(src_path, rb) as f: version, count, index_off read_header(f) entries read_index(f, count, index_off) # 用第一條記錄判斷偏移基準(zhǔn) base resolve_base(entries[0][offset], index_off, HEADER_SIZE) for e in entries: f.seek(base e[offset]) data f.read(e[packed_size]) if e[flag] 1 and e[packed_size] ! e[raw_size]: try: data zlib.decompress(data) except zlib.error: pass # 標(biāo)志位不準(zhǔn)時(shí)保留原始數(shù)據(jù)避免整批失敗 dst safe_join(out_dir, e[name]) os.makedirs(os.path.dirname(dst), exist_okTrue) with open(dst, wb) as w: w.write(data) print(f解包完成: {count} 個(gè)條目 - {out_dir})resolve_base用的是 2.3 節(jié)的判斷邏輯。try/except zlib.error那層兜底很關(guān)鍵——我遇到過整包里flag字段全是 1、但實(shí)際只有一半數(shù)據(jù)壓縮過的情況沒有這層兜底腳本跑到一半就停了。3.4 解包完做一次完整性核對(duì)解包腳本跑完不報(bào)錯(cuò)不代表解出來的東西是對(duì)的。核對(duì)三件事文件數(shù)量是否等于count、每個(gè)文件的實(shí)際大小是否等于raw_size、隨機(jī)抽幾個(gè)文件看文件頭是不是正常的圖片或文本格式。def verify(out_dir, entries): bad [] for e in entries: p safe_join(out_dir, e[name]) if not os.path.exists(p): bad.append((e[name], missing)) continue size os.path.getsize(p) if e[raw_size] and size ! e[raw_size]: bad.append((e[name], fsize {size} ! {e[raw_size]})) print(f異常條目: {len(bad)}) for name, reason in bad[:20]: print( , name, reason)raw_size為 0 的條目要跳過大小比較有些包對(duì)空文件不寫這個(gè)字段。這一步跑完還是零異?；究梢哉J(rèn)為解包是干凈的可以進(jìn)入改資源、替換、再打包的流程了。4. 打包回寫偏移計(jì)算、壓縮策略和頭部回填打包比解包難難在順序。文件頭里要寫索引偏移索引里要寫每個(gè)文件的數(shù)據(jù)偏移而這兩個(gè)值都得等數(shù)據(jù)寫完才知道。常見做法是兩遍寫第一遍先占位寫頭部、再寫數(shù)據(jù)區(qū)、最后寫索引第二遍seek(0)回去把頭部真實(shí)值填上。這套流程只要偏移算對(duì)一次就能成功。4.1 先收集再排序保證偏移可復(fù)現(xiàn)打包前先把源目錄里所有文件收集成一個(gè)列表按相對(duì)路徑排序。排序不是為了好看是為了讓同樣的輸入每次都產(chǎn)出字節(jié)完全一致的包方便做版本對(duì)比和差分。def collect_files(src_dir): items [] for root, _, files in os.walk(src_dir): for fn in files: full os.path.join(root, fn) rel os.path.relpath(full, src_dir).replace(os.sep, /) items.append((rel, full)) items.sort(keylambda x: x[0]) return itemsos.path.relpath拿到的分隔符在 Windows 上是\統(tǒng)一替換成/存進(jìn)索引跟原包保持一致。這一步不做打出來的包在客戶端里可能整個(gè)目錄樹都找不到。4.2 壓縮策略什么時(shí)候壓、級(jí)別定多少不是所有文件都值得壓縮。貼圖、音頻這類本身已經(jīng)壓過的格式再用 zlib 壓一遍體積可能不降反升還白搭 CPU。常見做法是設(shè)一個(gè)閾值原始大小小于 1KB 的直接不壓壓完比原文件還大的也回退成不壓。def maybe_compress(raw: bytes, level6, min_size1024): if len(raw) min_size: return raw, 0 packed zlib.compress(raw, level) if len(packed) len(raw): return raw, 0 return packed, 1level6是速度和壓縮比的平衡點(diǎn)。如果你只是改了幾個(gè)文件做測試用level1更快如果是發(fā)布用的完整包level9能再省一點(diǎn)體積但打包時(shí)間會(huì)翻倍。返回值第二個(gè)元素直接就是索引里的flag壓縮標(biāo)志和數(shù)據(jù)必須同源產(chǎn)生不能一處判斷一處寫死。4.3 先寫數(shù)據(jù)、再寫索引、最后回填頭部這是整個(gè)打包流程的主干。注意文件指針的位置數(shù)據(jù)區(qū)從HEADER_SIZE開始寫每個(gè)文件前用f.tell()取當(dāng)前偏移寫完后這個(gè)偏移就是索引里要填的值。def pack(src_dir, dst_path, level6): items collect_files(src_dir) entries [] with open(dst_path, wb) as f: f.write(b\x00 * HEADER_SIZE) # 頭部先占位 for rel, full in items: with open(full, rb) as r: raw r.read() packed, flag maybe_compress(raw, level) offset f.tell() f.write(packed) entries.append({ name: rel, offset: offset, packed_size: len(packed), raw_size: len(raw), flag: flag, }) index_off f.tell() for e in entries: name_bytes e[name].encode(gbk) f.write(struct.pack( ENTRY_FMT, len(name_bytes), e[offset], e[packed_size], e[raw_size], e[flag], )) f.write(name_bytes) f.seek(0) f.write(struct.pack( HEADER_FMT, bGDF\x00, 1, len(entries), index_off )) print(f打包完成: {len(entries)} 個(gè)條目 - {dst_path})幾個(gè)參數(shù)要盯住bGDF\x00必須跟原包一致客戶端可能校驗(yàn)?zāi)?shù)版本號(hào)1如果原包是別的值照抄原包的值文件名編碼gbk要跟解包時(shí)探測到的編碼一致。這三處任何一個(gè)對(duì)不上客戶端都會(huì)判定文件損壞。4.4 拿解包腳本當(dāng)反向測試用例打包完最省事的驗(yàn)證方式就是用第 3 章的unpack把剛打出來的包重新解開再跟源目錄逐文件比對(duì)哈希。這一步跑通說明頭部、索引、數(shù)據(jù)區(qū)三段自洽。import hashlib def sha1(path): h hashlib.sha1() with open(path, rb) as f: for chunk in iter(lambda: f.read(65536), b): h.update(chunk) return h.hexdigest() def diff_dirs(a, b): bad [] for rel, full in collect_files(a): other safe_join(b, rel) if not os.path.exists(other) or sha1(full) ! sha1(other): bad.append(rel) return bad先unpack(new.gdf, verify_out)再diff_dirs(src_dir, verify_out)返回空列表才算通過。這個(gè)測試用例的價(jià)值在于它不依賴客戶端純本地就能判斷包結(jié)構(gòu)是否正確改代碼之后的回歸成本幾乎為零。5. 避坑與排查五個(gè)讓腳本當(dāng)場翻車的細(xì)節(jié)5.1 解出來全是亂碼多半是偏移基準(zhǔn)搞反了現(xiàn)象很典型文件數(shù)量對(duì)得上文件名也對(duì)得上但打開每個(gè)文件都是亂碼或者圖片頭PNG變成了別的字符。原因基本是索引里的偏移是相對(duì)數(shù)據(jù)區(qū)起點(diǎn)的腳本卻按絕對(duì)偏移去seek讀到的位置整體偏了index_offset那么多字節(jié)。解決辦法是把resolve_base的兩個(gè)分支各跑一次看哪一次解出來的文件頭正常。判斷依據(jù)很直接正常 PNG 前四字節(jié)是\x89PNG正常 XML 開頭是?xml一眼就能認(rèn)出來。5.2 中文路徑在幾千條之后才炸現(xiàn)象是腳本前面跑得好好的突然在某一條上拋UnicodeDecodeError而且每次炸的位置還不一樣。原因是包里文件名編碼混用大部分是 GBK個(gè)別是 UTF-8甚至同一個(gè)包里兩種都有。硬編碼一個(gè)編碼必然翻車。解決辦法是用 2.2 節(jié)的decode_name回退鏈先把所有文件解出來再統(tǒng)計(jì)哪些名字命中了 UTF-8 分支心里有個(gè)數(shù)。打包回去時(shí)如果改了文件名編碼也要跟著原包走別解包用 GBK、打包用 UTF-8。5.3 壓縮標(biāo)志位不可信解壓失敗要能降級(jí)現(xiàn)象是zlib.decompress拋Error -3 while decompressing data腳本中斷后面的文件一個(gè)都沒解出來。原因是索引里的壓縮標(biāo)志寫的是 1但數(shù)據(jù)區(qū)那一段其實(shí)沒壓。這類包通常是工具鏈不同版本混著打出來的。解決辦法是解壓外面包一層try/except失敗就原樣輸出同時(shí)在日志里記一筆解完之后再人工看那幾個(gè)文件是不是正常。整批任務(wù)不能因?yàn)橐粭l記錄異常就全停這是批量處理的基本原則。5.4 包能打出來客戶端就是不認(rèn)現(xiàn)象是自制的包用解包腳本能完整解開但客戶端加載時(shí)直接報(bào)資源損壞或者黑屏。原因通常有三個(gè)魔數(shù)或版本號(hào)寫錯(cuò)、索引項(xiàng)沒有按原包順序排列、文件名大小寫跟原包不一致。前兩個(gè)查頭部和索引就能發(fā)現(xiàn)第三個(gè)最隱蔽——Windows 上不區(qū)分大小寫解包時(shí)文件名被規(guī)范化了打包回去就變了而客戶端在別的平臺(tái)上按精確匹配找文件。解決辦法是解包時(shí)保留原始字節(jié)別經(jīng)過任何大小寫轉(zhuǎn)換打包時(shí)用的就是解出來的原始名字。5.5 覆蓋原包之前沒留后悔藥現(xiàn)象是打包腳本參數(shù)寫反輸出路徑指向了源包幾百 MB 的原文件瞬間被覆蓋客戶端直接報(bào)廢。原因不是技術(shù)問題是流程問題但沒有這個(gè)習(xí)慣遲早出事。我的做法是打包函數(shù)入口強(qiáng)制檢查目標(biāo)文件已存在時(shí)先重命名成.bak再寫或者干脆要求輸出目錄必須跟輸入目錄不同。多花兩行代碼省一次重下客戶端的麻煩。6. 批量解包加版本差分找出兩個(gè)包里到底改了什么單包解包跑通之后真正省時(shí)間的用法是做版本對(duì)比。手上同時(shí)有新老兩個(gè)客戶端是常事想知道某次更新動(dòng)了哪些資源靠人工翻目錄不現(xiàn)實(shí)。把兩個(gè)包分別解到old/和new/按相對(duì)路徑做并集逐個(gè)算 SHA1輸出一張變更表就行。狀態(tài)含義后續(xù)動(dòng)作added只在 new 里存在新增資源重點(diǎn)關(guān)注配置和腳本removed只在 old 里存在被刪資源檢查是否有引用殘留modified兩邊都有但哈希不同改動(dòng)內(nèi)容優(yōu)先看配置表和 UI 圖same哈希一致忽略def diff_packs(old_dir, new_dir, out_csvdiff.csv): old_map {rel: full for rel, full in collect_files(old_dir)} new_map {rel: full for rel, full in collect_files(new_dir)} names sorted(set(old_map) | set(new_map)) rows [] for rel in names: if rel not in old_map: rows.append((rel, added)) elif rel not in new_map: rows.append((rel, removed)) elif sha1(old_map[rel]) ! sha1(new_map[rel]): rows.append((rel, modified)) else: rows.append((rel, same)) with open(out_csv, w, encodingutf-8-sig) as f: f.write(path,status\n) for rel, status in rows: f.write(f{rel},{status}\n) return rowsencodingutf-8-sig是為了讓表格軟件直接打開不亂碼這點(diǎn)小細(xì)節(jié)在交付給別人時(shí)很加分。collect_files復(fù)用第 4 章那份路徑分隔符已經(jīng)統(tǒng)一過兩邊能直接對(duì)上。跑完之后按status過濾modified里優(yōu)先看.ini、.txt、.lua這類文本資源改動(dòng)往往就藏在那里added里如果有新目錄基本能推斷出這次更新加了什么系統(tǒng)。更進(jìn)一步的做法是增量打包只把modified和added的條目重新壓進(jìn)去其余條目從原包里按偏移直接拷貝字節(jié)不做解壓再壓縮。這樣打一個(gè)幾百 MB 的包只需要幾秒而不是幾分鐘。實(shí)現(xiàn)上就是在寫數(shù)據(jù)區(qū)時(shí)判斷該條目是否在變更集合里在的話走maybe_compress不在的話seek到原包對(duì)應(yīng)偏移讀packed_size字節(jié)原樣寫出索引里的字段也照抄原值。這套邏輯我第一次寫的時(shí)候沒做偏移基準(zhǔn)的統(tǒng)一結(jié)果拷過來的數(shù)據(jù)整體錯(cuò)位解出來一半文件是壞的——從那以后我每次寫增量打包都強(qiáng)制先用差分腳本跑一遍全量對(duì)比確認(rèn)變更集合和字節(jié)偏移都對(duì)得上再動(dòng)手改包。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取