SuperAPI AI 工具集

saints-row-modding

编程与开发

查看项目

更新于 10-30 16:20

技能介绍

用途

本技能用于 Saints Row 3/4 系列 PC 版模组制作,以及 srforge 工作台的使用。目标游戏包括:Saints Row: The Third(原版 PC,asm_pc 版本 0x0B)、Saints Row IV / Re-Elected(asm_pc 版本 0x0C,存在 Workshop SDK)、Gat Out Of Hell(沿用 SRIV 格式 0x0C)。SRTT Remastered 使用不同的引擎/构建,不在覆盖范围内,不应假装支持。

首次写入前需加载 game-mod-memory 与 game-mod-versioned-workspace(路由规则适用)。

已验证的二进制格式

详细结构与布局见 references/formats.md,要点如下:

  • .vpp_pc / .str2_pc:Packfile 版本 0x0A,0x28 字节头部(描述符 0x51890ACE,头部 CRC 覆盖字节 0x0C..0x28),0x18 字节条目,2 对齐名称块,随后是负载。压缩+精简归档是对所有负载按顺序的单个 zlib 流。
  • .asm_pc:Asset Assembler(0xBEEFFEED),0x0B(SRTT)与 0x0C(SRIV)每个容器仅相差一个字节(compression_type)。重新打包 str2 必须更新其 ASM 容器:PackfileBaseOffset、TotalCompressedPackfileReadSize、每个 primitive 的 CPU/GPU 大小(gpu 文件为同名 .cNNN -> .gNNN)。ASM 更新缺失或失败必须让构建失败,绝不能静默发布。
  • .xtbl:制表符缩进的 XML;<Name> 子节点文本是记录标识(基于属性的解析会破坏重复项)。保留注释与格式。
  • le_strings:头部 id 0xA84C7F73;桶以 Volition CRC 做 hash&mask 键;UTF-16-LE NUL 结尾记录。
  • Volition CRC:标准 CRC-32 表,init 0,无最终 xor,输入小写。

加载优先级:松散文件 > patch_compressed.vpp_pc > patch_uncompressed.vpp_pc > 基础 vpp。编辑前始终解析出胜出者;存在补丁时编辑基础副本等于无效/错误的模组。

工具链(来源已验证)

  • ThomasJepp.SaintsRow rev133(Minimaul):提取/构建打包文件、Stream2(ASM<->XML)、字符串、声音库。许可证允许在署名并回链的前提下再分发(保留 license.txt)。固定版本:https://minimaul.saintsrowmods.com/files/tools/releases/ThomasJepp.SaintsRow-rev133.7z。已知回归:CustomizationItemClone 在 rev121 之后的许多条目上失败——克隆请用 rev121。完整源码 zip(含工具 Program.cs 源码):https://minimaul.saintsrowmods.com/files/tools/saintsrowmods-src.zip。
  • Gibbed.Volition:较老的 SRTT 时代替代方案;社区分支各异。
  • Zinyak's Cache of Wonders:Volition 官方 SRIV SDK:https://github.com/volition-inc/Zinyaks-Cache-Of-Wonders(peg_assemble/mesh/rig/texture crunchers、vPkg、FBX 转换器)。无许可证文件 -> 仅限获取,绝不再分发。

SRIV Workshop 模组支持部分表合并(只发布变更的记录)——表类模组优先采用该形态。

已知陷阱

  • ThomasJepp.SaintsRow.BuildPackfile.exe 对游戏 srtt 抛出 NotImplementedException(仅支持 sr2/sriv/srgooh)。SRTT 构建请使用原生写入器(见下方 srforge),并用 TJ ExtractPackfile 重新打开做交叉工具验证。
  • 所有 ThomasJepp CLI 在 stdout 被管道且参数解析失败时会因 Console.BufferWidth 抛出 IOException。不要依赖 --help;只用真实参数调用。用法签名在源码 zip 的 Program.cs 中。
  • Stream2.exe <file.asm_pc> update 会从同级 str2 文件刷新 ASM;动作:clean/toasm/toxml/update。
  • 旧版 FBX 转换器需要 Python 2.6 + wxPython + FBX SDK 2014——需隔离或推迟;属于经典的手动操作依赖。

srforge 工作台(本机)

从安装副本运行:%LOCALAPPDATA%\SaintsRowForge;源码仓库 S:\Apps\Saints Row Tools\SaintsRowForge(GitHub:SenjuWoo/SaintsRowForge,发布 v0.1/v0.2,CI 保护)。修改仓库代码后刷新安装:在仓库根目录执行 powershell -File Update.ps1(robocopy /MIR)。

会话设置:

export SRFORGE_GAME_SRTT="S:\SteamLibrary\steamapps\common\Saints Row the Third" export SRFORGE_GAME_SRIV="S:\SteamLibrary\steamapps\common\Saints Row IV"

原生读写器:src/srforge/formats/{vpp,vpp06,asm,xtbl,strings,crc,lua}.py(SRTT=vpp06 原生写入器;SRIV=vpp0A;已做往返测试)。

核心:workspace/transaction/receipts/toolbroker/discovery/index 位于 src/srforge/core/(+ merger.py)。游戏目录为只读源;模组在工作区构建;回执记录每次操作的旧→新值。

CLI(src/srforge_cli.py,处处支持 --json):doctor、asset find/origin/extract、xtbl query/patch/diff、mod new/patch/diff/build、deps import、merge——跨模组表合并: srforge merge --game sriv ModA/ ModB/ → 相对原版的三方并集,冲突记录在 merge-report.json(后列出的模组胜出),非表冲突会被标记。

MCP 服务器:mcp_server/server.py——13 个 stdio JSON-RPC 工具,含 sr_knowledge_search;未全局注册(token 成本)——按需启动。

知识层:python %LOCALAPPDATA%\SaintsRowForge\scripts\KnowledgeSearch.py "<topic>" 搜索 knowledge/*.md + SOURCES.json 上游映射。

测试:python tests/run_tests.py(18 项检查,合成夹具)。

收件箱/保险库:下载 → 哈希 → tools_vault/ + manifest.json(sha256 固定)。

项目状态与恢复指针:references/srforge-project.md。

工作流骨架

  1. srforge doctor——游戏是否找到?工具是否就绪?能力矩阵是否如实?
  2. 在任何提取之前,先索引原版(考虑优先级)。
  3. 每个模组一个工作区;只提取胜出的副本。
  4. 结构化编辑(XTBL 操作 / Lua lint),绝不对打包数据做盲目正则。
  5. 重建 str2 -> 更新 ASM -> 重新打开并验证包(退出码为零不等于成功)。
  6. 与原版做语义差异;出现意外附带变更 = 构建失败。
  7. 记录带证据级别的回执;运行时行为始终需要游戏内测试。

适用场景与限制

适用于 SRTT(原版 PC)、SRIV / Re-Elected、Gat Out Of Hell 的 PC 模组制作,尤其是打包文件、ASM、XTBL 表、字符串与 Lua 相关编辑,以及跨模组表合并。不适用于 SRTT Remastered。部分工具(如旧版 FBX 转换器)依赖老旧环境,需隔离处理。官方 SDK 无许可证文件,仅限获取、不可再分发。