Minimaul's Saints Row 2, Saints Row: The Third, Saints Row IV and Gat Out Of Hell tools

Discussion in 'Tool Releases' started by Minimaul, Aug 19, 2013.

  1. Minimaul

    Minimaul Site owner Staff Member

    There is an ongoing issue with Rev 128, Rev 130 & Rev 131, Rev 132 and CustomizationItemClone. For many items it will fail to clone. If you need CustomizationItemClone, continue to use Rev 121:

    This toolset is made up of several tools:

    Packfile tools
    • ThomasJepp.SaintsRow.BuildPackfile.exe: A command line packfile builder that can optionally update asm_pc files when building str2_pc files. Ideal for use in batch files. Supports SR2, SRIV, SRGOOH.
    • ThomasJepp.SaintsRow.BuildPackfileGUI.exe: An easy to use GUI packfile builder that can update asm_pc files when building str2_pc files. Supports SR2, SRIV, SRGOOH.
    • ThomasJepp.SaintsRow.EditPackfile.exe: A command line tool to insert new files or replace existing files inside a vpp_pc or str2_pc file. A 64-bit version is also provided for use when working on large packfiles. Supports SR2, SRIV, SRGOOH.
    • ThomasJepp.SaintsRow.ExtractPackfile.exe: A command line packfile extractor. Ideal for use in batch files when extracting packfiles - vpp_pc and str2_pc files. Supports SR2, SRTT, SRIV, SRGOOH.
    • ThomasJepp.SaintsRow.ExtractPackfileGUI.exe: A simplified GUI packfile extractor. Ideal for use when extracting individual packfiles - vpp_pc and str2_pc files. Supports SR2, SRTT, SRIV, SRGOOH.
    • ThomasJepp.SaintsRow.RecursiveExtractor.exe: A command line tool that can extract all of the packages from a game in one operation. Requires quite a bit of disk space and takes quite a while to run. Supports SR2, SRTT, SRIV, SRGOOH.
    • ThomasJepp.SaintsRow.Stream2.exe: A command line tool that can update asm_pc files, and convert asm_pc files to and from an editable XML format. Supports SRTT, SRIV, SRGOOH.
    • ThomasJepp.SaintsRow.Stream2Update.exe: A tool that automatically extracts the necessary asm_pc files for your current mods and updates them appropriately. Supports SRIV, SRGOOH.
    Localisation tools
    • ThomasJepp.SaintsRow.BuildStrings.exe: A command line localisation string builder. Converts an editable XML format to the le_strings files that the game needs. Works with non-english characters such as Japanese or Russian. Supports SR2, SRTT, SRIV, SRGOOH.
    • ThomasJepp.SaintsRow.ExtractStrings.exe: A command line localisation string extractor. Converts le_strings files to an editable XML format. Supports SR2, SRTT, SRIV, SRGOOH.
    Soundbank tools
    • ThomasJepp.SaintsRow.BuildStreamingSoundbank.exe: A command line soundbank builder - for soundbanks that end in _media.bnk_pc. Supports SRTT, SRIV, SRGOOH.
    • ThomasJepp.SaintsRow.ExtractStreamingSoundbank.exe: A command line soundbank extractor for streaming soundbanks (ones that end in _media.bnk_pc). Supports SRTT, SRIV, SRGOOH.
    Misc tools
    • ThomasJepp.SaintsRow.ConvertClothSim.exe: A command line tool to convert cloth simulation files (.sim_pc) between Version 2 (SRTT/SRIV) and Version 5 (SRGOOH).
    • ThomasJepp.SaintsRow.CustomizationItemClone.exe: A command line tool that clones customization items - so you can edit the clone, not the original. Supports SRIV only.


    The tools are available for download from this post (as attachments) and the source code is available at:

    These tools and their source code are licensed to you under the terms included in "license.txt" in the downloadable copy. You can also view a copy online.

    For help with these tools, post in the Get Help/Troubleshooting forum for Saints Row IV, and for tutorials on how to use these tools check out the Guides and Tutorials forum.

    If you're a more advanced user trying to use the command line tools, just run them in a command prompt with no parameters and they should show you a reasonable amount of help text.

    Only the most recent version is attached to this post, and it is the only recommended version to use. If you have a problem with the tools, make sure you are using the most recent version before you report a bug!
    If you need to, you can download older versions from:

    To use these tools on Linux/SteamOS, you need an up to date version of Mono.

    For Debian, Ubuntu and SteamOS, I suggest following these instructions to add the Mono repository to your APT configuration, then running apt-get install mono-complete.

    Please note: ThomasJepp.SaintsRow.ExtractStreamingSoundbank can't convert audio on Linux as it relies on Windows programs where the source code is not available.

    Some tools use third-party programs for full functionality:
    These tools are included in the main download.

    Change log
    • Revision 132:
      • Fix BuildStreamingSoundbank and ExtractStreamingSoundbank for SR3 soundbank files
    • Revision 131:
      • Fix ExtractStrings and BuildStrings for SR2 US string files (there's no US charlist for SR2)
    • Revision 130 (2017/03/25):
      • BuildStreamingSoundbank now creates files with correct alignment, and actually repacks the lipsync data (oops!)
    • Revision 128 (2016/12/25):
      • Stream2Update will now let you select the third game in the list (oops!).
      • Generate shorter filenames for some files in CustomizationItemClone.
      • Some tweaks to language string tools internally.
    • Revision 121 (2016/10/12):
      • CustomizationItemClone now handles items with more than one wear option correctly - these seem to be mostly hairstyles.
    • Revision 120 (2016/09/23):
      • Write out the cmorph_pc file loose too for CustomizationItemClone (fixes an issue with morphs not being correctly applied in the clothing store)
      • Add a "settings.json" file that allows you to specify paths for each game. If the path is set to null the game will attempt to autodetect the paths. For now, autodetection only works on Windows. This allows tools to be used with the GOG versions of SR and the Linux/SteamOS versions. Please report any issues you hit using the tools on Linux/SteamOS especially.
      • Remove the "clean" action from ThomasJepp.SaintsRow.Stream2 - it was never intended to be actually used.
      • Update some of the usage information shown by the command line tools when you run them in a command prompt with no parameters.
    • Revision 111 (2016/05/12):
      • Fix a crash in CustomizationItemClone when an item has missing language strings.
    • Revision 110 (2016/05/12):
      • Actually package the right files this time.
    • Revision 108 (2016/05/12): - this is a broken revision, do not use!
      • Add ThomasJepp.SaintsRow.CustomizationItemClone.
    • Revision 102 (2016/05/12):
      • Add ThomasJepp.SaintsRow.ConvertClothSim to convert cloth sim files between Version 2 (SRTT/SRIV) and Version 5 (SRGOOH)
      • Add a better error message to Stream2Update when it can't find any games to update.
      • Implement lots of extra file formats including basic Peg support and static mesh support (metadata only - you can't use this to edit the contents of these files).
    • Revision 94 (2016/03/17):
      • Add support for Saints Row: The Third ASM files.
      • Updates & bugfixes to ThomasJepp.SaintsRow.dll
      • Add ThomasJepp.SaintsRow.EditPackfile - allowing for easy substitutions of files into a packfile.
    • Revision 81 (2015/10/19):
      • Include some cmd files to allow for easy soundbank extraction. Simply drag your soundbank onto one of these files to extract it:
        • extract-soundbank-sr3.cmd - for Saints Row 3
        • extract-soundbank-sr4.cmd - for Saints Row 4
        • extract-soundbank-srgooh.cmd - for Saints Row: Gat out of Hell
      • Main download now includes revorb.exe, ww2ogg.exe and the two packed codebooks files
    • Revision 79 (2015/08/21):
      • Fix building strings files when there is a hash in the file that couldn't be turned into a name.
    • Revision 78 (2015/08/20):
      • Fix ExtractStrings when working with SRTT string files - it was attempting to open SRIV only packfiles - thanks Fan of Saints!
    • Revision 77 (2015/08/20):
      • Add read-only support for Saints Row: The Third packages.
      • Fix some compile-time warnings.
      • Added MakeDummyClothSim & updated HashTester - these tools aren't included in the main distribution, but the source code is on github.
    • Revision 72 (2015/04/08):
      • Added support for Saints Row 2 package files to BuildPackfile, BuildPackfileGUI, ExtractPackfile and ExtractPackfileGUI.
    • Revision 67 (2015/04/05):
      • ExtractStreamingSoundbank and BuildStreamingSoundbank now extract and repack subtitles that are attached to voice clips. The parameters on these tools have changed!
      • ExtractStreamingSoundbank and BuildStreamingSoundbank now automatically tries to select the right codebooks for revorb. You can also override this manually with the /codebooks:<codebook file> parameter.
      • BuildStrings and ExtractStrings now work correctly on non-latin characters - so they should work on Russian/Polish/Japanese. The parameters on these tools have changed! These tools now also use an XML file format rather than an awkward text file format.
      • ExtractStrings now automatically finds your xtbl files inside the game's original packfiles and uses those.
      • Finding your game install directory is now much more reliable and should even work for cases where your game installed to a different Steam library.
    • Revision 54 (2015/02/17):
      • Add two new modes to Stream2 - "toxml" and "toasm" - these convert ASM files to/from easily editable XML files.

        To convert to an XML file:
        ThomasJepp.SaintsRow.Stream2.exe customize_item.asm_pc toxml
        This will create customize_item.xml

        To convert back to an ASM file:
        ThomasJepp.SaintsRow.Stream2.exe customize_item.xml toasm
        This will create customize_item.asm_pc
    • Revision 50 (2015/01/31):
      • When overwriting old files, make sure that we actually *replace* the old file rather than just opening the old one. This meant that if we were overwriting a file with one that was smaller, the contents of the old file were left on the end. (oops!)
    • Revision 49 (2015/01/29):
      • Make Steam2Update ignore the "mods" folder if it exists - this folder has never worked for all mods and shouldn't be used. Thanks to Arioh for noticing this was a problem with GOOH!
    • Revision 47 (2015/01/25):
      • Add BuildStreamingSoundbank and ExtractStreamingSoundbank for manipulating streamed soundbanks. ExtractStreamingSoundbank can also be used to convert audio when extracting.
      • Fix a bug with extracting already modified packfiles that are condensed and compressed (such as soundboot.vpp_pc).
      • ExtractPackfile will now create an "extracted-" prefix on extracted packfiles if you do not specify an output directory.
    • Revision 32 (2015/01/20):
      • Add some missing SRIV archives to the built-in lists.
      • If you try to use the GUI extractor to extract a packfile to the same folder it was already in, a "extracted-" prefix will be added to the folder name.
      • Add support for Gat Out Of Hell in Stream2Update. Stream2Update now detects games when it first runs and allows you to select the game you wish to update.
    • Revision 22 (2013/09/21):
      • Make Stream2Update check that the paths it finds for SRIV in the registry are actually correct. Try some backup paths if they are not.
      • Add the correct settings for dlc3.vpp_pc, dlc4.vpp_pc, patch_compressed.vpp_pc and patch_uncompressed.vpp_pc to the built-in list of packfiles.
      • Fix extracting preload_anim.vpp_pc and preload_rigs.vpp_pc.
      • Fix building preload_anim.vpp_pc, preload_rigs.vpp_pc, and soundboot.vpp_pc.
    • Revision 18 (2013/08/31):
      • Don't automatically close Stream2Update when finished.
    • Revision 17 (2013/08/31):
      • Tiny change to ThomasJepp.SaintsRow.Stream2Update.
    • Revision 16 (2013/08/31):
      • added ThomasJepp.SaintsRow.Stream2Update
      • fixed building normal vpp_pc files - all vpp_pc files now build and work OK except preload_anim.vpp_pc, preload_rigs.vpp_pc and soundboot.vpp_pc.
    • Revision 12 (2013/08/19): first release.

    Attached Files:

    Last edited by a moderator: Apr 25, 2020
  2. 100000% awesome already!
  3. Well clothing mods be possible with the tools?
  4. [V] IdolNinja

    [V] IdolNinja Volition Staff

    Weapons/clothing/vehicle/npc creation will be possible in the future with the actual SDK release. These are just basic tools for file formats and editing scripts/tables; similar to our existing SR2 and SRTT tools. Keep your eye on the announcements forum for future details regarding the SDK.
  5. The command line version doesn't appear to be working (at least for me). I drag and drop a SR4 VPP_PC file onto the executable and it gives me an unhandled IO exception stating that "a file or directory with the same name already exists".

    The GUI version works like a champ.

    EDIT: Just noticed that your tools for SR4 are including the extension as part of the folder name. So instead of getting "misc_tables" for a folder name it now gives "misc_tables.vpp_pc".
    Last edited: Aug 20, 2013
  6. Minimaul

    Minimaul Site owner Staff Member

    Yeah - you will need to extract files to a different folder to the ones that they came from. Drag/drop isn't really ideal.
  7. Thank you, kind sir.

    EDIT: Yup, I was being dumb, didn't think to try the extract packfile app on the str2_pc file. Works like a charm.
    Last edited by a moderator: Aug 20, 2013
  8. Sooo I tried packing the files back into a vpp_pc file and it just corrupts my game (luckily I backed up the specific file). And no it isn't because I changed something and mucked it up. I even tried just extracting the files, which worked, then not even touching it and packing it back into a vpp_pc and it still makes my game crash.
  9. Now that I have unpacked the str2_pc file of my choosing, how do I unpack the .cvbm_pc and .gvbm_pc files inside of it? The unpacker tool crashes when I try, if I'm supposed to use it. [using GUI version]
  10. Minimaul

    Minimaul Site owner Staff Member

    Try the SR3 texture tools - if they won't work then you'll have to wait for someone to release something that will.

    Can you tell me which vpp_pc you're trying to repack?
  1. This site uses cookies to help personalise content, tailor your experience and to keep you logged in if you register.
    By continuing to use this site, you are consenting to our use of cookies.
    Dismiss Notice