帕鲁存档改坏了 3 次之后我决定自己搞懂 Palworld 存档转 JSON 的每一层包装【免费下载链接】palworld-save-toolsTools for converting Palworld .sav files to JSON and back项目地址: https://gitcode.com/gh_mirrors/pa/palworld-save-tools如果你曾在深夜对着一个 90MB 的Level.sav手足无措如果你曾因为改坏一个数值导致整个基地凭空消失那么这篇关于 Palworld 存档转 JSON 的实战笔记就是为你写的。工具本身叫palworld-save-tools一个能把帕鲁存档从二进制魔窟里完整搬进 JSON 世界的转换器而它最打动我的不是能转而是转了还能原样转回去。文章较长建议先收藏。核心观点一句话存档编辑这件事90% 的翻车都发生在没搞懂数据结构上而不是不会用工具上。一、先讲我的一次翻车通用编辑器把我的帕鲁变成了乱码事情是这样的。第一次想改存档我随手找了个通用的 Unreal 引擎存档编辑器双击打开Level.sav界面倒是很华丽但点开角色数据一看帕鲁的属性全是乱码基地建筑信息直接空白工位分配表完全读不出来。为什么因为 Palworld 在标准 GVAS 格式Unreal 引擎的存档封装格式可以理解为集装箱里塞了大量游戏自定义的数据块。通用编辑器只认识集装箱不认识里面的货。它把帕鲁数据当成普通字节流一显示当然就是天书。而palworld-save-tools干的事是把集装箱里的每一件货都拆出来、贴上标签、翻译成人话。它针对帕鲁 v0.1.4.0 起几乎所有已知数据结构做了专门的解码器数据结构它在游戏里是什么GroupSaveDataMap公会、组织等社交关系CharacterSaveParameterMap玩家和帕鲁的完整属性MapObjectSaveData地图物件与建筑系统ItemContainerSaveData箱子、背包等物品容器BaseCampSaveData基地营地的完整配置WorkSaveData工位与工作分配逻辑这套拆箱能力就是它和通用工具最本质的区别。这也是为什么社区里一堆衍生项目帕鲁可视化编辑器 PalEdit、服务器管理工具 palworld-server-tool、存档迁移工具 palworld-host-save-fix全都选择踩在它肩膀上——因为别的工具拆不了这箱货。二、五个想当然每一个都差点毁了我的存档在我和这份工具磨合的过程中踩过的坑基本可以归纳成五个想当然。提前说破你能少走我走过的弯路。想当然 1转出来的 JSON 可以直接用记事本打开真相转换Level.sav会生成非常大的文件动辄几百 MB。记事本打开直接卡死就算打开了也无法滚动。正解用 VS Code、JetBrains 系 IDE 或 Sublime Text 这类现代编辑器。想快速定位内容可以先用命令行工具jq做筛选比如只查某个玩家 ID 下的字段而不是硬扛整个文件。想当然 2转完 JSON 就等于可以随便改真相JSON 只是换了个格式里面的值依然受游戏数据结构约束。你把帕鲁等级改成 99999游戏照样读得进去但数值溢出可能导致存档行为异常。正解修改值保持在游戏逻辑允许的范围内并且每次只改一小部分改完立刻转回去进游戏验证。批量大改之前先给原始存档做备份。想当然 3转回 SAV 的文件和原来一模一样所以随便改真相这是最容易让人放松警惕的一点。好在palworld-save-tools把可逆性当成头等大事——它保证SAV JSON SAV 全程压缩前逐比特一致。也就是说你不做任何修改地转一圈得到的文件和原文件完全一致一个字节都不差。正解利用这个特性做差分验证——先转一圈再转回去比对文件哈希比如sha256sum确认环境没问题之后再开始动数据。这样出了问题你能立刻排除转换器本身有损这个嫌疑。想当然 4要解析完整存档就必须把所有数据都解码真相处理大型Level.sav时全量解码是内存杀手。很多时候你只想改公会数据却被迫把角色、基地、工作系统全部过一遍。正解用--custom-properties做选择性解析。只解码你关心的数据类型其余原样跳过。后面有具体命令。想当然 5Windows 上拖拽.sav到convert.cmd没反应 工具坏了真相convert.cmd会依次尝试python3、python、py三个命令如果系统里 Python 的应用执行别名被开启命令会被 Windows 商店的占位程序劫持表现为拖了没反应。正解在 Windows 设置里搜索管理应用执行别名关掉 Python 相关别名或者干脆放弃拖拽直接用命令行。三、它最值钱的设计把正确性写进了开发哲学如果说前面是使用层面的经验这一节才是这个项目真正的灵魂。README 里白纸黑字写了两条开发哲学我建议每个想深入玩存档的人都读一读正确性优先于性能。SAV JSON SAV 应产出比特级一致的文件压缩前。这句话翻译成大白话宁可慢不能错。对一个存档编辑器来说这是非常清醒的取舍。因为存档是玩家的身家性命一个字节的偏差可能意味着一个帕鲁消失、一个基地错位、甚至整个存档无法读取。而比特级一致意味着你改了什么就只有什么变了其他一切保持原样。另一条哲学同样耐人寻味零外部依赖。脚本应当能在默认安装的 Python 上直接运行。为什么不引入一堆第三方库作者在 README 里解释得很直白打包分发 Python 二进制文件时杀毒软件很容易误报。零依赖意味着分发干净、部署简单、没有供应链风险。性能优化则通过可选依赖解决——比如想更快就用pip install palworld-save-tools[performance]换装高性能实现不想要就纯标准库跑。三层包装的拆解理解了哲学再看它的架构就豁然开朗了。整个转换过程就是一层层剥洋葱.sav 文件 │ ① palsav.py识别 PlZ 魔数解包 zlib 压缩层0x31 单层 / 0x32 双层 ▼ GVAS 数据流 │ ② gvas.py解析 Unreal 头部、属性树这是标准部分 ▼ 属性字典 │ ③ rawdata/针对帕鲁自定义结构逐块解码 ▼ 可读 JSONrawdata/目录下每个文件负责一类数据character.py管角色、base_camp.py管基地、group.py管公会……每个模块都自带decode二进制→字典和encode字典→二进制两个方向所以转换是严格可逆的——这正是比特级一致能成立的结构基础。纯标准库的代价与补偿零依赖不是没有代价的标准库的 JSON 序列化在几百 MB 的数据面前确实慢。所以项目提供了两条补偿路径安装时可选[performance]扩展如recordclass换取更快的运行时转换时用--minify-json输出紧凑 JSON文件更小、后续处理更快。一句话总结它的设计取向用一层薄薄的 Python 标准库做最严谨的格式还原把性能问题留给可选的优化开关。四、实战从 0 到 1 完成一次安全的存档手术环境要求很简单Python 3.9 或更新版本。获取方式也很简单——git clone https://gitcode.com/gh_mirrors/pa/palworld-save-tools之后进入目录即可不需要安装任何依赖。第一步确认基线强烈建议做先验证你的环境能无损往返python convert.py Level.sav sha256sum Level.sav Level.sav.json # 记录原始文件的哈希 python convert.py Level.sav.json sha256sum Level.sav # 转回来的文件哈希应完全一致如果你的原始文件哈希和转回来的完全一致说明转换链路是干净的可以放心开工。第二步按需解码而不是全量解码假设你只想改公会数据其他一概不管python convert.py Level.sav \ --custom-properties .worldSaveData.GroupSaveDataMap只解码公会数据角色、基地、物品全部跳过内存占用和耗时肉眼可见地下降。想同时处理多类用逗号分隔即可python convert.py Level.sav \ --custom-properties .worldSaveData.GroupSaveDataMap,.worldSaveData.CharacterSaveParameterMap.Value.RawData第三步改数据、压体积、转回去在 JSON 里完成修改后python convert.py Level.sav.json --minify-json工具会根据文件扩展名自动判断方向.sav转 JSON.json转回 SAV不用记方向参数。以下几个参数是高频使用的参数作用什么时候用--minify-json输出紧凑 JSON文件太大 / 给脚本消费--force覆盖已存在的输出文件反复迭代修改时--output指定输出路径想存到别的位置--to-json/--from-json强制指定转换方向扩展名不标准时--custom-properties选择性解码内存吃紧 / 只改部分数据--convert-nan-to-nullNaN 转 null下游工具不支持 NaN 时不开终端的方案Windows 拖拽把.sav文件拖到convenience_tools/convert.cmd上松手等它生成 JSON改完把 JSON 再拖一次转回 SAV。Steam 版存档一般在%LOCALAPPDATA%\Pal\Saved\SaveGames\SteamID\SaveID下。如果拖拽没反应参考第二节的想当然 5排查。五、什么时候该用什么姿势一张决策表不同场景对解析深度内存占用速度的需求完全不同别一套参数走天下你的场景推荐姿势原因单人改几只帕鲁默认全量 现代编辑器图省事直接全解服务器批量处理多个存档--minify-json脚本化省磁盘、方便脚本消费只想改公会/角色--custom-properties定向解码内存占用最低、速度最快完整备份存档全量解析 哈希校验备份要的是完整性与可验证性写代码的开发者还可以直接把它当库用pip install palworld-save-toolsfrom palworld_save_tools.paltypes import PALWORLD_TYPE_HINTS # 查看角色数据的类型提示路径 hint PALWORLD_TYPE_HINTS.get( .worldSaveData.CharacterSaveParameterMap.Value.RawData )注意项目仍在快速迭代pip install时建议锁定具体版本号避免上游破坏性变更影响你的脚本。六、如果你还想往深里走工具再强也只是翻译官真正决定你能改出什么的是对数据结构本身的理解想看懂帕鲁属性读rawdata/character.py看decode如何把字节流拆成objectgroup_id想自己扩展解析在rawdata/下新建模块实现decode/encode两个方向再注册进paltypes.py的PALWORLD_CUSTOM_PROPERTIES想追性能看gvas.py的解析循环或换用[performance]可选依赖。每次游戏大版本更新palworld-save-tools都会跟进新增的数据结构。它的 Roadmap 上还挂着两件事解析所有已知数据块、继续优化 CPU 与内存占用。这意味着这个工具不是一锤子买卖而是会跟着游戏一起进化的长期投资。最后给你一个可直接照做的行动清单今天克隆项目跑一遍哈希校验确认环境无损往返第一次修改只改一个数值比如某个物品数量转回去进游戏验证形成习惯每次大改前备份原文件用--custom-properties只解码要动的部分进阶读完rawdata/里你感兴趣的那个模块试着看懂一类数据怎么被拆解和重组。存档是你的世界而palworld-save-tools只是那个把二进制黑箱翻译成可读文本的可靠翻译官。搞懂它你才真正拥有对这个世界的数据支配权。【免费下载链接】palworld-save-toolsTools for converting Palworld .sav files to JSON and back项目地址: https://gitcode.com/gh_mirrors/pa/palworld-save-tools创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考