SuperAPI AI Directory

saints-row-modding

Coding & development

View repository

Updated 10-30 16:20

About this skill

Saints Row modding (SRTT + SRIV family)

Load game-mod-memory and game-mod-versioned-workspace before first write (router rules apply).

Targets

Game Notes
Saints Row: The Third (original PC) asm_pc version 0x0B
Saints Row IV / Re-Elected asm_pc version 0x0C; Workshop SDK exists
Gat Out Of Hell Shares SRIV formats (0x0C)
SRTT Remastered DIFFERENT engine/build — NOT covered; do not pretend

Verified binary formats

Details + struct layouts: references/formats.md. Headlines:

  • .vpp_pc / .str2_pc = Packfile version 0x0A: 0x28-byte header (descriptor 0x51890ACE, header CRC over bytes 0x0C..0x28), 0x18-byte entries, 2-aligned name block, payload. Compressed+condensed archives are ONE zlib stream over all payloads in order.
  • .asm_pc = Asset Assembler (0xBEEFFEED): 0x0B (SRTT) vs 0x0C (SRIV) differ by exactly ONE byte per container (compression_type). Repacking a str2 REQUIRES updating its ASM container: PackfileBaseOffset, TotalCompressedPackfileReadSize, per-primitive CPU/GPU sizes (gpu file = same name with .cNNN -> .gNNN). Missing/failed ASM update must FAIL the build, never ship silently.
  • .xtbl = tab-indented XML; <Name> child TEXT is the record identity (attribute-based parsing breaks duplicates). Preserve comments/format.
  • le_strings = header id 0xA84C7F73; buckets hash&mask keyed by Volition CRC; UTF-16-LE NUL-terminated records.
  • Volition CRC = standard CRC-32 table, init 0, no final xor, lowercase input.
  • Load precedence: loose files > patch_compressed.vpp_pc > patch_uncompressed.vpp_pc > base vpps. Always resolve the winner before editing; editing the base copy when a patch exists = wasted/incorrect mod.

Toolchain (provenance-verified)

  • ThomasJepp.SaintsRow rev133 (Minimaul) — extract/build packfiles, Stream2 (ASM<->XML), strings, soundbanks. License permits redistribution WITH credit + link back (keep license.txt). Pin: https://minimaul.saintsrowmods.com/files/tools/releases/ThomasJepp.SaintsRow-rev133.7z. Known regression: CustomizationItemClone fails on many items >rev121 — use rev121 for cloning. Full source zip (has tool Program.cs sources): https://minimaul.saintsrowmods.com/files/tools/saintsrowmods-src.zip.
  • Gibbed.Volition — older SRTT-era alternative; community forks vary.
  • Zinyak's Cache of Wonders — official Volition SRIV SDK: https://github.com/volition-inc/Zinyaks-Cache-Of-Wonders (peg_assemble/mesh/rig/texture crunchers, vPkg, FBX converter). NO license file -> acquisition-only, NEVER redistribute.
  • SRIV Workshop mods support partial-table merging (ship only changed records) — prefer that shape for table mods.

Hard-won gotchas

  • ThomasJepp.SaintsRow.BuildPackfile.exe throws NotImplementedException for game srtt (supports sr2/sriv/srgooh only). For SRTT builds use a native writer (see srforge below) and validate by reopening with TJ ExtractPackfile (cross-tool validation).
  • ALL ThomasJepp CLIs crash with Console.BufferWidth IOException when stdout is piped AND args fail parsing. Never rely on --help; call with real arguments only. Usage signatures live in the source zip's Program.cs.
  • Stream2.exe <file.asm_pc> update refreshes ASM from sibling str2 files; actions: clean/toasm/toxml/update.
  • Legacy FBX converter needs Python 2.6 + wxPython + FBX SDK 2014 — isolate or defer; classic MANUAL ACTION REQUIRED dependency.

srforge workbench (this machine)

Run from the installed copy: %LOCALAPPDATA%\SaintsRowForge — source repo S:\Apps\Saints Row Tools\SaintsRowForge (GitHub: SenjuWoo/SaintsRowForge, releases v0.1/v0.2, CI-protected). After changing repo code refresh the install: powershell -File Update.ps1 from repo root (robocopy /MIR).

Session setup:

export SRFORGE_GAME_SRTT="S:\SteamLibrary\steamapps\common\Saints Row the Third"
export SRFORGE_GAME_SRIV="S:\SteamLibrary\steamapps\common\Saints Row IV"
  • Native readers/writers: src/srforge/formats/{vpp,vpp06,asm,xtbl,strings,crc,lua}.py (SRTT=vpp06 native writer too; SRIV=vpp0A; round-trip tested).
  • Core: workspace/transaction/receipts/toolbroker/discovery/index under src/srforge/core/ (+ merger.py). Game dirs are read-only sources; mods build in workspaces; receipts record per-op old→new values.
  • CLI (src/srforge_cli.py, --json everywhere): doctor, asset find/origin/ extract, xtbl query/patch/diff, mod new/patch/diff/build, deps import, merge — cross-mod table merge: srforge merge --game sriv ModA/ ModB/ → three-way union vs vanilla, conflicts logged in merge-report.json (later-listed mod wins), non-table collisions flagged.
  • MCP server: mcp_server/server.py — 13 stdio JSON-RPC tools incl. sr_knowledge_search; NOT registered globally (token cost) — launch on demand.
  • Knowledge layer: python %LOCALAPPDATA%\SaintsRowForge\scripts\KnowledgeSearch.py "<topic>" searches knowledge/*.md + SOURCES.json upstream map.
  • Tests: python tests/run_tests.py (18 checks, synthetic fixtures).
  • Inbox/vault: downloads → hashed → tools_vault/ + manifest.json (sha256 pinned).

Project state and resume pointers: references/srforge-project.md.

Workflow skeleton

  1. srforge doctor — game found? tools ready? capability matrix truthful?
  2. Index vanilla (precedence-aware) BEFORE any extraction.
  3. Workspace per mod; extract winning copies only.
  4. Structured edits (XTBL ops / Lua lint), never blind regex on packed data.
  5. Rebuild str2 -> ASM update -> reopen-and-verify package (zero exit code is NOT success).
  6. Semantic vanilla diff; unexpected collateral changes = FAIL the build.
  7. Receipt with evidence level; runtime behavior always needs in-game test.