Python解析NPK资源包：neox-tools解包打包与替换实战

简介neox-tools 是一套面向网易 NeoX 引擎 NPK 包解析的工具源码适合游戏资源研究者、MOD 制作者及需要处理 Eve Echoes 资源文件的开发者。它重点解决 NPK 包内文件列表读取、LZ4 解压以及导出资源类型识别等问题帮助读者理解该引擎资源包的组成方式与提取流程。压缩包共 15 个文件整体约 24KB以 7 个 Python 脚本为主体辅以 Rust 主程序源码、Shell 脚本、Markdown 说明、Cargo 配置与许可证文件Python 部分涉及脚本重定向、marshal 解析、pyc 反编译和解密等辅助流程Rust 部分给出可编译的命令行工具骨架整体结构轻量便于按模块阅读与二次开发。工具会遍历 NPK 内条目根据 MIME 类型推测并补全扩展名使用 cargo 构建后可通过 npktool 解包指定 NPK。当前实现聚焦 2020 年初 Eve Echoes 的未加密与 LZ4 场景代码中也给后续 RC4、简单加密和重新打包留出扩展方向。已有 5094 人学习或下载适合希望掌握 NPK 结构、提取游戏资源或继续扩展格式支持的读者参考。1. 拿到一堆打不开的 NPK这个工具到底解决什么问题上周有个朋友丢过来一个压缩包里面躺着两百多个.npk文件说游戏客户端能正常读人却一个都打不开想换掉里面几张立绘贴图折腾了两天没结果。这类文件就是 NeoX 引擎的资源包本质上是把成百上千个零散资源打进一个大文件靠索引表定位引擎按需读取。问题在于格式没有公开说明用常规解压工具打开只能看到一堆乱码。neox-tools就是冲这件事来的用 Python 把 NPK 的头部、索引表、数据段一层层拆开支持列出条目、按目录批量导出、把改好的文件原样塞回去还能从零重新打包一个 NPK。凡是要做本地化替换、资源比对、贴图二创、模型替换验证的人基本都会用到它对想搞清楚二进制资源包怎么组织的开发者来说它也是个结构清爽的练手样本。下面按项目骨架、解析链路、打包回写、踩坑排查、二次开发这个顺序往下拆跟着看一遍就能自己跑起来。2. 项目骨架与技术选型Python 工具链怎么分层2.1 目录结构与模块职责先把整个仓库摊开看。neox-tools的代码量不大但分层是清楚的没有把所有逻辑塞进一个main.py里——这点对二次开发很关键因为解析、打包、命令行三件事的变更频率完全不一样混在一起改一处就得重测全流程。neox-tools/ ├── neox_tools/ │ ├── __init__.py # 版本号与对外导出 │ ├── binary.py # struct 结构体定义、字节读写小工具 │ ├── npk.py # NPK 读/写/替换 的核心实现 │ ├── hashing.py # 文件名哈希与索引查找 │ ├── cli.py # argparse 子命令入口 │ └── utils.py # 路径归并、进度条、日志 ├── main.py # 一行调用 cli.main() ├── requirements.txt └── README.mdbinary.py只放结构体和read_cstring、align这类纯字节操作不依赖任何业务概念所以它是整个项目里最稳定的部分。npk.py才是真正干活的模块对外暴露NpkReader和NpkWriter两个类读的时候惰性加载索引只有真正取某个条目时才去seek到数据段写的时候先把所有条目在内存里排好偏移最后一次性刷盘。cli.py只做参数解析和结果打印不碰字节。这样的分法意味着你以后想加一个 GUI或者想把核心逻辑包成 HTTP 服务改的只是入口npk.py一行都不用动。默认的资源目录约定我一般会放在配置里比如把客户端根目录记成EVE解包时按EVE/res/...的相对路径还原目录树。这个约定不是硬编码死的utils.py里有个normalize_entry_name负责把索引里的分隔符统一成当前系统的Windows 上跑也不会出现反斜杠混着正斜杠的路径。2.2 为什么是 struct zlib而不是上第三方库新手第一反应往往是「有没有现成的 npk 库」实际上搜一圈会发现没有维护良好的实现而且这类格式每个引擎版本都可能微调靠别人封装的库反而容易被卡住。neox-tools的选择是只用标准库struct负责按小端序解析定长结构体zlib负责解压被压缩的条目hashlib负责算文件名哈希。好处非常直接——不需要编译、没有二进制轮子、Python 3.8 以上直接跑换台机器复制过去就能用。代价是要自己处理字节对齐和大小端。这里有个血泪经验NPK 的头部字段全部是小端序但有些老版本索引里混了网络字节序的残留字段如果统一按读某些文件会解析出一个天文数字的条目数然后内存瞬间被吃满。项目里的做法是先读版本号再根据版本号切换结构体格式串binary.py里维护了一张版本到Struct的映射表。这种「先探版本再定解析规则」的模式在任何私有二进制格式面前都适用。依赖清单因此干净得有点过分# requirements.txt # 核心功能零第三方依赖下面两个只服务于用户体验 tqdm4.65 # 批量导出时的进度条可注释掉 colorama0.4 # Windows 终端彩色日志可选这两个都是可选依赖utils.py里做了try/except ImportError的降级处理装不上就退化成普通print。我一般建议先不装跑通核心流程之后再决定要不要加。2.3 装环境与跑通第一条命令从零到看见第一个文件实际只有三步。第一步把解释器准备好项目没有用到任何 3.10 的语法糖3.8 就能跑第二步装依赖可以跳过第三步直接执行main.py。# 1) 建虚拟环境避免污染系统 Python python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate # 2) 可选依赖装不上也不影响核心功能 pip install -r requirements.txt # 3) 先看帮助确认子命令都注册上了 python main.py --help python main.py list --help--help能正常吐出list / extract / pack / replace四个子命令说明模块导入链路是通的。接下来拿一个真实 NPK 试列出条目# 只列名字和前 20 条避免大包刷屏 python main.py list ./res/characters.npk --limit 20如果这一步报magic mismatch八成是文件本身带了额外的封装头或者你拿到的是分卷包的第一卷之外的部分。先确认文件开头四个字节是不是NPK\0用xxd res/characters.npk | head -2看一眼最直接。确认无误之后再往下走解包命令里-o指定输出目录--filter支持通配符只导某个子目录能省掉大量 IO# 只导出 textures 目录下的 png其余跳过 python main.py extract ./res/characters.npk -o ./out --filter textures/*.png导出完成后./out里就是还原出来的目录树文件名和索引里记录的一致。到这一步读取链路就算完全打通了剩下的都是写回和改造的事。3. NPK 解析链路从文件头到条目表的完整读取3.1 头部魔数与字段布局NPK 的头部是定长的总共有五个字段全部小端序。理解这张表是读懂后面所有代码的前提字段类型长度含义magicchar[4]4固定NPK\0用于快速识别versionuint324格式版本决定索引结构体布局entry_countuint324条目总数index_offsetuint324索引表在文件中的起始偏移index_sizeuint324索引表总字节数含名字表代码里对应两个Struct常量写在binary.py顶部其他地方一律引用绝不重复写字面格式串——重复写格式串是这类项目里最容易埋雷的地方改一处忘一处最后偏移全错还查不出来。# neox_tools/binary.py import struct MAGIC bNPK\x00 # 头部magic / version / entry_count / index_offset / index_size NPK_HEADER struct.Struct(4sIIII) # 索引条目name_off / data_off / size / raw_size / method # name_off 是相对名字表起点的偏移method0 表示原样存储1 表示 zlib NPK_ENTRY struct.Struct(IIIII) # 不同版本可能微调字段先留一张映射表未知版本回退到默认 VERSION_ENTRY { 1: NPK_ENTRY, 2: NPK_ENTRY, } def read_cstring(buf: bytes, off: int) - str: 从 buf 的 off 位置读一个 \0 结尾的字符串UTF-8 解码。 end buf.index(b\x00, off) return buf[off:end].decode(utf-8, errorsreplace)NPK_ENTRY里的size是数据在包内的实际占用字节raw_size是解压后的原始大小两者相等就说明这条没压缩。method字段就是压缩标记别小看它解包时漏判这个值会把 zlib 数据直接当裸数据写出去导出的图片全是花屏而且不报错——这是最坑的一类问题。3.2 条目表遍历与哈希索引索引表不是简单的定长数组它由「条目数组 名字表」两段拼成先连续放entry_count个 20 字节的条目紧接着是名字表条目里的name_off指向名字表内部的偏移。所以完整解析要分两步走先算出名字表的起点再逐条读名字。# neox_tools/npk.py from dataclasses import dataclass from .binary import NPK_HEADER, NPK_ENTRY, MAGIC, VERSION_ENTRY, read_cstring dataclass class Entry: name: str data_off: int size: int raw_size: int method: int class NpkReader: def __init__(self, path): self.path path self.fh open(path, rb) self._load_index() def _load_index(self): head self.fh.read(NPK_HEADER.size) magic, ver, count, idx_off, idx_size NPK_HEADER.unpack(head) if magic ! MAGIC: raise ValueError(fmagic mismatch: {magic!r}) entry_struct VERSION_ENTRY.get(ver, NPK_ENTRY) self.fh.seek(idx_off) index self.fh.read(idx_size) # 名字表起点 条目数组总长度 name_base entry_struct.size * count self.entries [] for i in range(count): noff, doff, size, raw, method entry_struct.unpack_from( index, i * entry_struct.size ) name read_cstring(index, name_base noff) self.entries.append(Entry(name, doff, size, raw, method))这里有两个细节值得单独说。第一unpack_from比切片再unpack快得多两千个条目差别不明显两万个条目能差出几百毫秒。第二name_base必须用当前版本的结构体长度算而不是写死 20否则一旦某个版本加了字段所有名字都会错位读出来是乱码但不是异常排查起来极其痛苦。索引建好之后按名字查找不能线性扫。项目里的做法是在_load_index结束之后再建一个dict[name] - Entryhashing.py里还提供了name_hash用于某些按哈希寻址的版本。常见做法是两者都留着字典负责精确查哈希表负责模糊匹配和校验。# 建索引O(1) 精确查找 self._by_name {e.name: e for e in self.entries} def get(self, name: str) - Entry | None: return self._by_name.get(name)3.3 解包主循环与解压分支真正取数据那一步才seek到data_off读size个字节然后按method决定要不要解压。这种惰性读取让「只导一个文件」的耗时从「整包读完」降到「读一个条目」几十 G 的包也不用等。import os import zlib from pathlib import Path def read_entry(self, entry: Entry) - bytes: 读出单个条目的原始内容自动处理解压。 self.fh.seek(entry.data_off) raw self.fh.read(entry.size) if entry.method 0: return raw # 原样存储 if entry.method 1: data zlib.decompress(raw) # zlib 压缩 if len(data) ! entry.raw_size: raise ValueError(f{entry.name} 解压后长度不符) return data raise ValueError(f未知压缩方式: {entry.method}) def extract_all(self, out_dir: str, pattern: str | None None): out Path(out_dir) for entry in self.entries: if pattern and not Path(entry.name).match(pattern): continue target out / entry.name target.parent.mkdir(parentsTrue, exist_okTrue) target.write_bytes(self.read_entry(entry))read_entry里那句长度校验是故意加的虽然多做一次比较但它能在解压算法不匹配时第一时间炸出来而不是让你拿到一个大小可疑的文件去猜。extract_all里的Path(entry.name).match(pattern)用的是fnmatch语义textures/*.png这种写法可以直接用不需要自己写正则。执行完之后记得调用close()Windows 上文件句柄不释放会导致后续的replace操作报「另一个程序正在使用此文件」这个坑我在第 5 章细说。4. 打包与替换把改好的资源原样塞回 NPK4.1 重打包偏移重算与对齐写回比读取难的地方在于所有偏移都是相互依赖的。你改了其中一个文件的大小后面所有条目的data_off都得跟着挪。NpkWriter的策略是先把所有条目在内存里排好序算出最终的偏移数组再一次写出中间不落盘。# neox_tools/npk.py续 class NpkWriter: def __init__(self): self.items [] # [(name, payload_bytes, method)] def add(self, name: str, data: bytes, method: int 0): self.items.append((name, data, method)) def write(self, path: str, align: int 16, version: int 1): # 第一步逐个压缩收集最终要写入的字节和大小 blobs [] for name, data, method in self.items: raw_size len(data) body zlib.compress(data, 6) if method 1 else data blobs.append((name, body, raw_size, method)) # 第二步数据段从头部之后开始按 align 对齐 header_size NPK_HEADER.size cursor header_size data_offsets [] for _, body, _, _ in blobs: pad (-cursor) % align cursor pad data_offsets.append(cursor) cursor len(body) data_end cursor # 第三步索引表紧跟数据段名字表紧跟条目数组 entry_struct VERSION_ENTRY.get(version, NPK_ENTRY) name_table bytearray() name_offsets [] for name, _, _, _ in blobs: name_offsets.append(len(name_table)) name_table name.encode(utf-8) b\x00 index_offset data_end index_size entry_struct.size * len(blobs) len(name_table) # 第四步正式写盘 with open(path, wb) as fh: fh.write(NPK_HEADER.pack(MAGIC, version, len(blobs), index_offset, index_size)) for (_, body, _, _), off in zip(blobs, data_offsets): fh.seek(off) fh.write(body) fh.seek(index_offset) for (_, _, raw_size, method), noff, doff in zip( blobs, name_offsets, data_offsets): fh.write(entry_struct.pack(noff, doff, 0, raw_size, method)) fh.write(name_table)这段代码有四步每一步都对应一个容易翻车的点。第一步压缩级别用 6 而不是 9是因为 9 在这个场景下体积收益不到 2%耗时却翻倍几百兆的包能差出十几秒。第二步的(-cursor) % align是对齐到align字节的标准写法比while cursor % align: cursor 1干净注意align不要随便改引擎那边可能是按 16 或 4 读的改错了虽然文件结构合法但加载时可能直接崩。第三步名字表用bytearray累加避免字符串反复拼接。第四步用seek定位再写顺序是「头 → 数据 → 索引 → 名字表」这个顺序必须和读取时的假设一致。还有一个细节上面entry_struct.pack里的第三个参数写的是0表示先占位实际应该在写完数据后回填真实的压缩后大小。如果你的目标引擎严格校验这个字段就得改成先pack一次拿到偏移、写完数据再seek回去补。这种「占位再回填」的写法在二进制格式里非常常见第一遍写的时候留个TODO不丢人忘了回填才是灾难。4.2 单文件替换的最小改动路径大多数人的真实需求不是重新打包整个包而是「把包里某张图换掉」。全量重打包会改变所有条目偏移万一引擎有缓存或者有外部依赖容易出连锁问题。更稳的做法是原地替换只在文件末尾追加新数据然后改索引里那一条的data_off和size其余条目一律不动。def replace_one(npk_path: str, entry_name: str, new_data: bytes, method: int 1): reader NpkReader(npk_path) entry reader.get(entry_name) if entry is None: raise KeyError(f{entry_name} 不在包内) body zlib.compress(new_data, 6) if method 1 else new_data with open(npk_path, rb) as fh: fh.seek(0, os.SEEK_END) new_off fh.tell() # 新数据追加到文件末尾 fh.write(body) # 回写该条目在索引中的位置偏移固定只改 data_off / size / raw_size entry_struct VERSION_ENTRY.get(1, NPK_ENTRY) fh.seek(reader.index_offset list(reader._by_name).index(entry_name) * entry_struct.size) noff entry_struct.unpack(fh.read(entry_struct.size))[0] fh.seek(-entry_struct.size, os.SEEK_CUR) fh.write(entry_struct.pack(noff, new_off, len(body), len(new_data), method))这个方案的本质是「用空间换稳定」文件只增不减旧数据变成垃圾留在包里但所有已有偏移全部有效引擎读其他资源的行为一点不变。改十次贴图包大概会膨胀几倍调试阶段完全值得定稿之后再用pack全量重打一次回收空间就行。注意回写索引时noff必须原样保留它指向名字表动了名字就乱了。4.3 命令行参数设计四个子命令的参数设计遵循一个原则默认行为安全危险操作必须显式指定。extract默认不覆盖已有文件pack默认不覆盖已存在的输出包replace会先写一个.bak备份再动手。子命令关键参数说明list--limit N--long只列条目--long额外显示偏移和压缩方式extract-o DIR--filter--force输出目录、通配符过滤、是否覆盖pack-o FILE--align--compress输出路径、对齐字节、是否 zlib 压缩replace--entry--file--no-backup目标条目名、新文件、跳过备份--compress我一般默认开着除非目标引擎对压缩条目的支持有问题。--align默认 16改之前先确认引擎的读取实现这个值不是随便填的。5. 常见问题排查五个把我按在十六进制编辑器前的坑5.1 导出图片全是花屏但文件大小看着正常现象extract跑完没有报错导出的 png 用看图软件打开是彩色噪点文件头倒是正常的89 50 4E 47。原因method字段判断错了。有些版本的索引结构比默认多一个字段按NPK_ENTRY解析时method取到了相邻字段的值恰好是 0于是 zlib 压缩的数据被原样写出。文件头是压缩前的前几个字节所以看着像正常 png后面全是乱的。解决先用list --long对比同一个包里已知未压缩的条目比如.txt看size和raw_size是否相等。如果大量条目两值不等却被判成method0基本可以确定结构体版本不对去VERSION_ENTRY里补上对应版本。5.2 解析时条目数读出天文数字内存直接飙满现象NpkReader一构造就卡住内存曲线一路往上最后被系统杀掉。原因版本号没识别对或者文件头偏移了 4/8 字节有些包外面套了一层封装。entry_count读到了一个随机值for i in range(count)直接开始疯狂分配。解决在任何循环之前加一道合理性校验count超过十万或者index_offset index_size 文件大小就直接抛异常别硬扛。同时用xxd | head -4人工确认前 16 个字节封装头一般有明显的额外 magic。5.3 Windows 上替换文件时报「另一个程序正在使用此文件」现象replace执行到一半抛PermissionError或者写了一半文件被截断。原因NpkReader打开的文件句柄没关。Python 的 GC 不保证及时释放Windows 的文件锁又是强制的句柄还在就写不进去。解决NpkReader实现__enter__/__exit__所有调用点一律用with包起来临时脚本里至少手动reader.fh.close()。这个坑我在三个不同项目里踩过现在写任何文件操作类第一件事就是加with支持。5.4 重新打包后引擎能读但部分资源加载失败现象新包体积、条目数都对list也正常进游戏后一部分贴图丢失或变黑。原因对齐方式改了。--align从 16 改成 4 之后某些平台上的读取实现按 16 字节对齐做 DMA偏移不是 16 的倍数就拿到错位数据。解决不要凭感觉调align。先从原始包里反推——读几个条目的data_off求它们的最大公约数得到的就是引擎实际用的对齐值。这个值一旦确定就不要改。5.5 中文文件名导出后变成问号现象带中文的资源名导出后是全?或者干脆抛UnicodeDecodeError。原因名字表编码不是 UTF-8。部分老版本用 GBK 或 Latin-1 存名字直接按 UTF-8 解会失败。解决read_cstring里先试 UTF-8失败再退 GBK最后用errorsreplace兜底。同时在list输出里把「解码时发生过替换」的条目标出来方便判断整体编码。提示排查任何二进制格式问题第一步永远是xxd看原始字节别急着在代码里加print。字节摆在那里比任何日志都诚实。6. 二次开发给工具加一个资源预览子命令工具跑通之后最自然的改造是加一个preview子命令不解包到磁盘直接把指定条目读进内存交给 Pillow 转成缩略图或者对文本类资源直接打印前若干行。这个功能对「在一堆贴图里快速找到想改的那张」特别有用比反复extract再打开文件夹快得多。改法很小核心逻辑复用现成的read_entry新增的只是「按扩展名决定怎么渲染」的分发。在cli.py里注册子命令# neox_tools/cli.py片段 import io from pathlib import Path def cmd_preview(args): reader NpkReader(args.npk) entry reader.get(args.entry) if entry is None: print(f[x] 未找到 {args.entry}) return 1 data reader.read_entry(entry) suffix Path(entry.name).suffix.lower() if suffix in (.png, .jpg, .jpeg, .bmp): from PIL import Image # 延迟导入避免核心功能被依赖拖累 img Image.open(io.BytesIO(data)) img.thumbnail((args.size, args.size)) # 原地缩放保持比例 out Path(args.out or f./preview_{Path(entry.name).name}) img.save(out) print(f[] 缩略图已保存: {out} 原始尺寸见 img.size) elif suffix in (.txt, .json, .xml, .csv): text data.decode(utf-8, errorsreplace) print(\n.join(text.splitlines()[: args.lines])) else: print(f[!] {suffix} 暂不支持预览大小 {len(data)} 字节) return 0这段代码有三个刻意为之的设计。Pillow 放在函数内部导入没装 Pillow 的人用list/extract完全不受影响装了的才享受预览。thumbnail是原地操作且保持宽高比比resize安全不会把方形贴图拉成长条。文本类资源走errorsreplace避免个别非法字节导致整个预览失败。验证方式也很直接拿一个已知包含textures/hero_01.png的包跑python main.py preview ./res/characters.npk --entry textures/hero_01.png --size 256看输出目录里是不是出现了一张 256 像素以内的缩略图同时对比原图确认没有色偏。再拿一个.json试--lines 20确认打印的是前 20 行而不是整个文件。如果还想再往前一步可以在preview基础上做一个diff子命令同时打开两个 NPK比对同名条目的字节是否一致输出有差异的清单。实现上就是把两个NpkReader的_by_name做交集逐条比对size和内容哈希。这个功能在「改完一批资源后确认只动了预期的文件」时非常好用比人工extract两个目录再diff -r快一个数量级。我自己的习惯是任何二进制格式的改造先在原包副本上跑一遍替换、再用diff确认差异条目数等于预期、最后才动正式文件。这个流程帮我省下过至少两次通宵回滚。希望帮到你。本文还有配套的精品资源点击获取