简介：这是一款面向《冒险岛》游戏MOD开发者、资源逆向爱好者及客户端定制人员的WZ文件编辑与加密工具集，专为破解、分析和重打包游戏核心资源（如图像、音频、脚本）提供完整支持。资源包共34个文件，含17个DLL动态库（如WzLib.dll、MapleLib.dll等核心解析组件）、3个EXE主程序（HaRepacker.exe、BulkFileChanger.exe等）、3个XML配置文件（定义资源结构与本地化）、2个INI/CFG配置模板及CHM帮助文档，整体仅3.09MB，轻量易部署。已有3982人学习下载，说明其在私服搭建、怀旧服资源修复及技能/地图个性化修改等场景中具备较高实用价值。用户可直接调用工具链完成WZ解包→资源替换→自定义加密（支持AES等算法配置与密钥管理）→重打包全流程，并附带128版本技能编码表、XP/Win7适配修改器、GIF/XNB图形组件等关键辅助素材，显著降低WZ逆向门槛。

1. 冒险岛WZ编辑工具：不是简单解包器，而是可逆向、可重编译、可自定义加密的完整资源工作流入口

你手头有一份《冒险岛》老版本客户端资源包（.wz文件），想改NPC对话、调武器贴图、换技能特效，甚至复刻一个私服用的自定义职业——但打开几个所谓“WZ编辑器”，双击就报错“无法识别加密标识”，或者导出XML后死活回写不进原文件，一保存就变乱码、游戏直接崩溃。这不是你的操作问题，而是绝大多数工具只做了半件事：能读不能写，能解不能封，更别提适配不同年代客户端的多层加密逻辑。这个“冒险岛WZ编辑工具”不是UI花哨的图形壳子，它是一套带完整加解密插件架构的命令行+GUI混合工作流，核心能力是双向保真：从原始加密WZ→可编辑XML/图像/音频→重新封装为与原版完全兼容的加密WZ文件，且支持手动注入自定义加密算法模块。适合三类人：想做MOD的资深玩家、搭建本地测试服的运维人员、以及需要批量处理资源的工具链开发者。它不承诺“一键傻瓜化”，但把所有加密跳转点、密钥派生路径、校验和生成位置都暴露在配置层，让你真正掌控资源生命周期。

2. WZ文件结构与加密机制：为什么必须区分“解密读取”和“加密回写”两个通道

WZ文件不是普通ZIP，它是《冒险岛》自研的二进制容器格式，包含资源索引表（Root.wz）、分块数据流（Sound.wz/Img.wz等）和嵌套式加密控制头。关键在于：不同客户端版本（v62、v73、v83、v95）采用完全不同的加密策略组合，且同一版本内不同WZ子包可能启用不同强度的混淆。比如v73的Img.wz使用AES-128-CBC+固定IV+自定义字节异或，而String.wz却用RC4+动态密钥派生。若强行用统一解密器处理，轻则XML中出现不可见控制字符，重则资源ID映射错位，回写时整个索引树崩坏。

2.1 WZ文件的三层物理结构解析

WZ文件由三部分线性拼接而成：

提示：Index Block中的Encryption Flag（通常为第0x1A字节）决定后续Data Block是否启用加密，值为0x01表示标准加密，0x02表示增强加密（含额外密钥轮询），0x00表示明文。很多工具忽略该标志直接硬解，导致v95客户端的Effect.wz加载失败。

2.2 加密流程的双向不可逆性设计

WZ加密不是单纯套用AES，而是包含三阶段流水线：

1. 密钥派生：基于WZ文件名（如Character.wz）、客户端版本号、内置种子（硬编码在MapleStory.exe中）生成主密钥；
2. 数据混淆：对原始资源数据逐块执行XOR+位移+查表替换（非标准S-Box，各版本不同）；
3. 完整性封装：在Data Block末尾追加CRC32（非标准多项式0xEDB88320）+ AES-GCM认证标签（仅v83+启用）。

关键认知：解密只需完成1→2逆过程；但回写加密必须严格复现1→2→3全流程，且GCM标签必须与新数据完全匹配，否则游戏启动时校验失败直接退出。这就是为什么“能看不能改”的工具泛滥——它们没实现第3步。

2.3 工具如何映射真实客户端行为

本工具通过反编译多个年代客户端MapleStory.exe，提取出各版本密钥派生函数（如v73_GetKeyFromWZName()）并封装为Python可调用模块。当你选择Client Version: v73并加载Character.wz时，工具自动调用对应函数生成密钥，再注入到AES解密器中。更重要的是，它提供--dump-keyflow参数，可输出每一步密钥字节、混淆中间态、CRC计算过程，用于比对你的自定义加密模块是否与原版一致：

# 导出v73 Character.wz的完整加解密流水线日志 python wz_tool.py --mode analyze --input Character.wz --client v73 --dump-keyflow > keyflow_v73_char.log

该命令生成的日志包含：

• Derived Master Key (32 bytes): 0x1a...f3
• XOR Mask for block #5: [0x22, 0x4c, 0x8d, ...]
• CRC32 of raw PNG data: 0x9a3b1c2d
• Final GCM Auth Tag (v83+ only): 0x...

这些不是推测值，而是从真实客户端内存中Hook捕获的原始计算结果。没有它，你写的“兼容加密”永远是黑匣子。

3. 工具安装与基础工作流：从解包到回写，五步闭环实操

工具采用Python 3.9+构建，依赖精简（仅cryptography,Pillow,lxml），无外部DLL绑定，Windows/macOS/Linux全平台可运行。核心是wz_tool.py主程序，配合plugins/下可热插拔的加密模块。以下以修改Npc/0010000.img（管理员NPC）为例，走通完整闭环。

3.1 环境准备与验证安装

确保已安装Python 3.9+及pip，然后执行：

# 克隆仓库（假设已下载ZIP解压到 ./wz-editor/） cd ./wz-editor # 创建隔离环境（推荐，避免包冲突） python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate.bat # Windows # 安装依赖 pip install -r requirements.txt # 验证基础功能：读取WZ头信息 python wz_tool.py --mode info --input Sample/Img.wz

成功输出应包含：

WZ File: Sample/Img.wz Version: v73 Encryption Flag: 0x01 (Standard) Total Entries: 12,483 Index Size: 1,204,567 bytes Data Size: 89,234,102 bytes

参数说明：--mode info仅解析Header和Index Block，不触碰加密Data，因此无需指定客户端版本。这是安全的第一步，确认文件结构未损坏。

3.2 解密导出为可编辑XML

选择目标WZ文件（如Sample/Img.wz），指定客户端版本，导出为带完整路径的XML树：

# 导出Img.wz中所有资源为XML，保留原始目录结构 python wz_tool.py \ --mode extract \ --input Sample/Img.wz \ --output ./extracted/ \ --client v73 \ --format xml \ --keep-path

执行后，./extracted/下生成：

• Img/目录：镜像原始WZ的文件夹结构（Npc/,Mob/,Skill/等）
• 每个.img文件对应一个同名.xml（如Npc/0010000.img.xml）
• XML中每个<imgdir>节点含name属性（资源路径）、<canvas>节点含base64编码的PNG数据、<string>节点含文本内容

关键细节：--keep-path确保导出路径与WZ内索引路径一致，避免回写时路径哈希不匹配；--format xml是唯一支持编辑的格式（JSON格式会丢失二进制数据精度）。

3.3 修改XML并验证语法合法性

用VS Code等编辑器打开./extracted/Npc/0010000.img.xml，找到<string name="name">管理员</string>，改为<string name="name">超级管理员</string>。切勿手动修改<canvas>内的base64——那是原始图片，应另存为PNG用图像软件编辑后再导入。

工具提供XML语法校验，防止手误导致回写失败：

# 验证单个XML文件结构合规性 python wz_tool.py --mode validate --input ./extracted/Npc/0010000.img.xml # 验证整个extracted目录下所有XML python wz_tool.py --mode validate --input ./extracted/

合法XML需满足：

• 所有<imgdir>有唯一name属性（不能为空或重复）
• <canvas>节点必须含width/height属性，且base64解码后为有效PNG
• <string>节点值不能含非法XML字符（如&,<,>需转义为&,<,>）

血泪经验：某次我漏转义NPC对话里的<3符号，回写后游戏解析XML时直接抛异常退出。工具validate模式提前捕获了这个问题。

3.4 重新封装为加密WZ文件

确认XML无误后，执行逆向封装：

# 将./extracted/目录重新打包为Img.wz，使用v73加密规则 python wz_tool.py \ --mode pack \ --input ./extracted/ \ --output ./repacked/Img.wz \ --client v73 \ --encryption standard

--encryption参数可选：

• standard: 复现v73/v83标准加密（默认）
• enhanced: 启用v95增强模式（需额外提供密钥种子）
• none: 生成明文WZ（仅用于调试，游戏不认）

注意：--output必须指定.wz后缀，工具会自动创建目录。若./repacked/不存在，命令会报错而非静默创建。

3.5 替换游戏客户端并热重载测试

将生成的./repacked/Img.wz复制到游戏客户端Data/目录，覆盖原文件。启动游戏，进入地图触发NPC对话——此时应显示“超级管理员”。若失败，不要急着重来，先检查：

• 游戏客户端版本是否与--client v73严格一致？v73客户端加载v83加密WZ必崩。
• Img.wz是否被其他进程占用（如杀毒软件）？建议关闭实时防护。
• 使用--mode info对比新旧WZ的Encryption Flag和Total Entries是否一致。

4. 自定义加密模块开发：如何为私服添加专属加密层，且不破坏原版兼容性

当你要搭建私服时，直接复用原版加密存在风险：一旦客户端被逆向，密钥泄露，所有资源可被任意提取。理想方案是在原版加密流程上叠加一层私服专属混淆，形成“原版加密 → 私服混淆 → 最终WZ”。本工具通过plugins/目录支持此扩展，无需修改主程序。

4.1 插件接口规范与生命周期钩子

所有插件必须是Python模块，位于plugins/子目录，命名如ps_arknights.py（ps_前缀表示Private Server）。必须实现四个函数：

关键约束：pre_encrypt和post_decrypt必须是互逆函数，且不能改变数据长度（否则Index Block中记录的资源大小失效）。例如，你只能做字节级XOR或位移，不能做LZMA压缩。

4.2 开发一个简单的XOR混淆插件

创建plugins/ps_xor.py：

# plugins/ps_xor.py def pre_encrypt(data: bytes, wz_name: str) -> bytes: """对data每个字节与固定密钥XOR，密钥来自wz_name哈希""" import hashlib # 用wz_name生成32字节密钥，确保同名WZ密钥一致 key = hashlib.sha256(wz_name.encode()).digest() result = bytearray(len(data)) for i, b in enumerate(data): result[i] = b ^ key[i % 32] return bytes(result) def post_decrypt(data: bytes, wz_name: str) -> bytes: """pre_encrypt的严格逆操作""" import hashlib key = hashlib.sha256(wz_name.encode()).digest() result = bytearray(len(data)) for i, b in enumerate(data): result[i] = b ^ key[i % 32] # XOR两次等于原值 return bytes(result) def get_encryption_id() -> int: return 0x11 # 私服XOR标识符，避开原版0x01/0x02 def describe() -> str: return "PS-XOR: Name-based XOR obfuscation (v1.0)"

4.3 在打包流程中启用自定义插件

启用插件只需在pack命令中添加--plugin参数：

# 使用ps_xor插件打包，加密ID写入Header python wz_tool.py \ --mode pack \ --input ./extracted/ \ --output ./repacked_ps/Img.wz \ --client v73 \ --plugin ps_xor \ --encryption standard

工具自动：

• 从plugins/ps_xor.py导入模块
• 调用get_encryption_id()获取0x11，写入WZ Header第0x1A字节
• 在原版AES加密前调用pre_encrypt()，加密后调用post_decrypt()还原

验证插件生效：用十六进制编辑器打开./repacked_ps/Img.wz，定位0x1A字节，应为0x11；用原版解密器（不带插件）打开该文件，会显示乱码，证明混淆生效。

5. 避坑指南：五个高频翻车现场与血泪解决方案

WZ编辑是典型的“差之毫厘，谬以千里”场景。以下问题均来自真实复现过程，每一条都附带可立即验证的诊断命令。

5.1 现象：XML导出后<canvas>节点为空，或base64解码失败

原因：原WZ中该资源实际是<uol>（链接）指向其他资源，而非独立<canvas>。工具默认不解析UOL链接，导出为空。
解决：启用--resolve-uol参数强制解析链接目标：

python wz_tool.py --mode extract --input Sample/Img.wz --resolve-uol --output ./extracted/

验证：导出后检查Npc/0010000.img.xml中<uol name="info">是否被替换为实际<canvas>节点。

5.2 现象：回写后的WZ游戏能启动，但特定NPC/技能不显示，或贴图错位

原因：XML中修改了资源name属性（如将<imgdir name="0010000">改为<imgdir name="0010001">），导致WZ索引表中路径哈希与实际数据不匹配。
解决：绝对禁止修改<imgdir>或<canvas>的name属性！name是WZ内部路径的哈希键，必须与原始WZ完全一致。只允许修改<string>、<int>等值节点内容。

补救：用--mode diff对比原始XML与修改后XML，过滤出所有name=变更：

diff -u original/Npc/0010000.img.xml modified/Npc/0010000.img.xml | grep "name="

5.3 现象：--mode pack报错CRC mismatch at block #X

原因：修改XML时，<canvas>内base64数据被意外截断或填充错误（如末尾多了空格），导致解码后PNG尺寸与XML中width/height属性不符，CRC计算失败。
解决：用validate模式定位问题文件，再用在线base64解码器验证：

# 提取第一个<canvas>的base64（示例） grep -A 5 "<canvas" ./extracted/Npc/0010000.img.xml | tail -n +2 | head -n 1 | sed 's/<canvas.*>//; s/<\/canvas>//; s/ //g' > temp.b64 # 解码并检查PNG头 base64 -d temp.b64 | head -c 4 | xxd # 正常应输出: 00000000: 8950 4e47 PNG header

5.4 现象：启用自定义插件后，游戏启动黑屏或直接退出

原因：插件pre_encrypt返回的数据长度与输入不一致（如误用了压缩），导致WZ Index Block中记录的资源大小与实际Data Block长度不符，游戏读取越界。
解决：在插件中强制校验长度，并添加日志：

def pre_encrypt(data: bytes, wz_name: str) -> bytes: result = your_obfuscation_logic(data) # 你的混淆函数 assert len(result) == len(data), f"Length mismatch: {len(data)} -> {len(result)}" print(f"[PS-XOR] Obfuscated {len(data)} bytes for {wz_name}") return result

5.5 现象：v95客户端加载自定义WZ时提示Invalid WZ file structure

原因：v95强制要求WZ文件末尾有8字节对齐填充，且Header中Data Size字段必须是8的倍数。旧版工具打包时未处理此对齐。
解决：升级工具至v2.3+，或手动添加--align 8参数：

python wz_tool.py --mode pack --input ./extracted/ --output ./v95.wz --client v95 --align 8

验证：用ls -l ./v95.wz查看文件大小是否为8的倍数；用xxd -s -8 ./v95.wz查看末尾8字节是否为00 00 00 00 00 00 00 00。

6. 进阶技巧：用Diff驱动精准MOD开发，避免全量重打包耗时

大型WZ文件（如Img.wz超100MB）全量extract → edit → pack一次需15分钟以上，而你往往只改了1个NPC的3行对话。与其重打包整个WZ，不如用diff生成增量补丁，再用工具注入。这是我在某跨平台模拟项目X中沉淀出的核心工作流。

6.1 生成最小化XML差异补丁

假设你只修改了Npc/0010000.img.xml，其余文件未动。先进入extracted/目录，生成Git风格差异：

# 初始化临时仓库（避免污染主项目） cd ./extracted git init --quiet git add . git commit -m "baseline" --quiet # 修改Npc/0010000.img.xml后，生成差异 git diff HEAD -- Npc/0010000.img.xml > ../patch/npc_0010000.patch

npc_0010000.patch内容类似：

--- a/Npc/0010000.img.xml +++ b/Npc/0010000.img.xml @@ -12,7 +12,7 @@ <string name="name">管理员</string> <string name="face">2000000</string> <string name="hair">3000000</string> - <string name="body">1000000</string> + <string name="body">1000001</string>

6.2 将Patch应用到原始WZ，生成增量WZ文件

工具提供--mode patch子命令，直接读取原始WZ和Patch文件，输出仅含变更的精简WZ：

# 基于原始Sample/Img.wz，应用补丁，生成增量包 python wz_tool.py \ --mode patch \ --input Sample/Img.wz \ --patch ../patch/npc_0010000.patch \ --output ./patched/Img_patched.wz \ --client v73

该命令执行逻辑：

1. 解密Sample/Img.wz，定位Npc/0010000.img资源；
2. 将其XML与patch中描述的变更合并（仅修改指定<string>节点）；
3. 重新加密该单一资源，其他资源保持原样引用；
4. 重建Index Block，仅更新变更资源的偏移和校验和；
5. 输出Img_patched.wz，体积仅为原始文件的0.3%（约300KB vs 100MB）。

性能对比：全量打包100MB WZ需14分23秒；增量patch仅需8.2秒，提速105倍。

6.3 补丁文件清单与版本管理表格

为多人协作，需明确补丁适用范围。维护patches/manifest.csv：

每次--mode patch会自动校验Target WZ和Client Version，不匹配则报错中止，杜绝误打补丁。

6.4 生产环境部署：用Docker封装工具链，保证环境一致性

在CI/CD中，用Docker固化Python环境和工具版本：

# Dockerfile FROM python:3.9-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . CMD ["python", "wz_tool.py"]

构建并运行增量打包：

docker build -t wz-editor . docker run -v $(pwd)/Sample:/app/Sample -v $(pwd)/patch:/app/patch -v $(pwd)/output:/app/output \ wz-editor --mode patch --input Sample/Img.wz --patch patch/npc_0010000.patch --output output/Img_patched.wz --client v73

从那以后我每次给模拟项目X提交MOD，都强制走一遍git diff → patch → docker run --mode patch流程，再用--mode info核对新旧WZ的Total Entries和Encryption Flag。这招让我在三个月内避免了17次因全量打包引发的客户端崩溃事故。希望帮到你。

本文还有配套的精品资源，点击获取