Saints Row 3 and 4 Zone File Tools

[Quantum]

LATEST RELEASE, VERSION 3.0 [2017-05-07]

This package contains Windows command-line tools that can be used to work with zone files (*.czh_pc and *.czn_pc). This assumes you have some familiarity with the Windows command line.

The SRZoneTool converts Saints Row zone files (".czh_pc" and ".czn_pc") to XML format which can be edited with any text editor, and then converts these XML files back into valid zone files.

Zone files contain a large amount of data in a multitude of different formats. SRZoneTool converts all data to an XML format so it can be converted back to a zone file, but not all data is parsed. Unparsed data is converted to a list of bytes in hexadecimal. Parsed data is converted to easy-to-read named XML elements that can be easily edited.

The following data is parsed by SRZoneTool:

1. All fields in the zone header file (".czh_pc").
2. Object and Property fields in the zone data file (".czn_pc").

You can read about the data that is parsed in the "SR3 zone file format" thread written by Knobby from Volition.

Why would you want to edit zone files?

If you would like to change the location or orientation of an object on a map, you probably want to edit a zone file.

What Saints Row games does this work with?

• Saints Row: The Third
• Saints Row IV

Please Note: These tools do NOT work with Saints Row: Gat Out Of Hell.

INSTALLATION

Nothing needs to be installed. Just put the ".exe" files somewhere in your PATH and run them.

TOOLS

SRReadZone.exe

Parses and displays the contents of a zone header file and the corresponding zone data file. Type the command with no parameters to display a usage message.​

SRZoneTool.exe

Converts zone files to and from XML format. Type the command with no parameters to display a usage message. For more information about this tool, see the "SRZoneTool.html" document included in this package.​

SRZoneFinder.exe

Finds zone files closest to a set of coordinates. Type the command with no parameters to display a usage message.​

SRPatchFile.exe

Writes one or more bytes to specific locations in an existing file. Great for scripting!​

DOWNLOAD

The executables are available in the package attached to this post.
The source code and license is available in my GitHub repository at https://github.com/clarosa/SRZoneTools

LINUX

These tools should run fine under Linux with Mono. See this post for more information.

VERSION HISTORY

0.1 [2015-07-08] Initial release of SRReadZone tool.
0.2 [2015-07-09] Added "-n" normalize option to SRReadZone tool.
0.3 [2015-07-26] Initial release of SRZoneTool tool.
0.4 [2015-07-27] SRZoneTool now parses all known data structures. Can combine header and zone data in a single XML file. Full SR4 compatibility for all tools.
1.0 [2015-07-29] First official release. Updated XML format. Added SRReadZone.html document.
1.1 [2015-08-12] Added SRZoneFinder tool.
1.2 [2015-08-15] Added new command line options to SRZoneFinder tool. Reduced default verbosity in SRZoneTool.
1.3 [2015-09-16] Updated SRReadZone tool to parse zone file section type 0x2233 (crunched reference geometry) up to and including object coordinates.
2.0 [2015-09-27] Changes to SRZoneTool XML format (see details in readme.txt). Additional XML file validation.
2.1 [2016-10-17] Added "--position" and "--type" options to SRReadZone.
2.2 [2016-10-26] Added SRPatchFile tool.
2.3 [2016-12-18] Added object type names in SRReadZone and SRZoneTool. Changed all <description> elements to XML comments.
2.4 [2017-04-25] Added "audio_emitter" object type name in SRReadZone and ZRZoneTool.
2.5 [2017-05-01] Added the complete (?) list of object type names to SRReadZone and ZRZoneTool, contributed by Minimaul.
3.0 [2017-05-07] Updated SRZoneTool to parse and convert zone file section type 0x2233 (crunched reference geometry) up to and including object coordinates. Can still read XML files created by version 2.x.

SEE ALSO

If you'd like to learn more about Zone Files, here are some great links:

• Traffic and world zone questions - a detailed description of the various types of zone files and how they're used
  
• SR3 zone file format - lots of detail about the internal format of zone files

Tutorial: How to Move a Nav Point

THANK YOU

I want to express my sincere appreciation to Knobby at Volition for all the wonderful help and information he's provided which allowed me to make this tool.

If you have any questions/comments, I'd love to hear them!

 

[[V] Knobby]

You probably want to put a license on this code. Just so everyone is clear. You can check out choosealicense.com for a good starting place of what to pick.

Also, if you would host it on like github or something I would help a little with this. This might be a hollow offer though since I have soooo much time with nothing to do.

Zone 1610(one of my go-to zones) one SR4 is version 32, not 29. Did you get version 29 from SR3 zones?

 

[Quantum]

You probably want to put a license on this code. Just so everyone is clear. You can check out choosealicense.com for a good starting place of what to pick.

Thanks for the link! I will definitely try to find a license there. I know I should have some kind of license, but I wasn't sure what I should use and I just wanted to put the code here so people could try it out as soon as possible. This will help a lot.

Also, if you would host it on like github or something I would help a little with this. This might be a hollow offer though since I have soooo much time with nothing to do.

Ha ha ha! I know how it feels to have so much time with nothing to do! My real job keeps getting in the way of all this fun stuff, and somehow my family has this strange idea that I should spend time with them too!

I really appreciate your offer to help! That would be great! I use my own personal Subversion repository at home, but I've been wanting to try out GitHub for a while. I just didn't really have a good reason until now.

Zone 1610(one of my go-to zones) one SR4 is version 32, not 29. Did you get version 29 from SR3 zones?

Yes, since your original post about the zone format was for SR3, I didn't know if the format would be the same for SR4. I have only been working with SR3 files so far for my testing. But since you told me the formats are the same I will test some SR4 files when I have some time.

Also, one thing I've been wanting to do for a long time was to remove some doors in SR3 (the garage door to the Syndicate Tower and the pony barn door in Safeword) while in free roaming mode. That was one of my incentives for creating these tools. I found the Lua mission scripts that call mesh movers to remove the doors, but those mesh movers are only available in the mission zone files. I'd ultimately like to copy those mesh movers to a zone file that would be always loaded so I can remove the doors in free roaming mode. Does that sound like something that would even be possible?

I've also been making progress on the XML converter which is a much larger (and much more well structured) piece of code than the SRReadZone tool. It's not at a point where I can release anything yet, but if I can get it on GitHub maybe you can take a look. Again, I wish there was 48 hours in a day!

Thanks, again!

 

[[V] Knobby]

Yes, since your original post about the zone format was for SR3, I didn't know if the format would be the same for SR4. I have only been working with SR3 files so far for my testing. But since you told me the formats are the same I will test some SR4 files when I have some time.

Mostly, yes. I found these differences between the versions:

// 30		2011/09/29, - Store the Havok PF data
// 31		2012/05/15, - Add static collision models for triggers (memory reporting purposes).
// 32		2012/09/07, - Havok 2010.2 has different serialization format.

Also, one thing I've been wanting to do for a long time was to remove some doors in SR3 (the garage door to the Syndicate Tower and the pony barn door in Safeword) while in free roaming mode. That was one of my incentives for creating these tools. I found the Lua mission scripts that call mesh movers to remove the doors, but those mesh movers are only available in the mission zone files. I'd ultimately like to copy those mesh movers to a zone file that would be always loaded so I can remove the doors in free roaming mode. Does that sound like something that would even be possible?

if the doors are a different object you could also just nuke that object. More than one way, but I would think this is possible.

Again, I wish there was 48 hours in a day!

Tell me about it

 

[Voltarox]

I thank you Quantum for your good work on this tool and also thanks to Knobby for the informative insight on the zone file format.

May I ask you sir, in which archive are the zone files (*.czh_pc and *.czn_pc) located for SRTT ?

I have the full legal Steam version installed in the default location --> C:\Program Files (x86)\Steam\SteamApps\common\saints row the third

Is it possible to remove all the trees and utility poles along with the attached electrical lines for all zones in the free roam mode ?

Have you had any success thus far in editing zones ?

 

[Minimaul]

This is absolutely awesome to see.

I'll echo Knobby - it's a great idea to get the source code on github! You should be able to import your version history from SVN so that should help. And I would also probably submit a few things if you do so

I'd suggest you make a library that can read & write the zone format like I do for my tools, then build apps that use that library. That way it's possible for other people to make applications that use it, it also makes it easier if you need to reuse the same code in several different apps, and it means that you don't have to update code in three different apps - instead you just update one library. Much easier.

May I ask you sir, in which archive are the zone files (*.czh_pc and *.czn_pc) located for SRTT ?

Look at: https://saintsrowmods.com/search/Files/Results?game=2&searchTerm=czh_pc

 

[Voltarox]

Thank you Minimaul for the info.

 

[Quantum]

if the doors are a different object you could also just nuke that object. More than one way, but I would think this is possible.

I didn't even THINK of that! That would be a lot easier, if they are separate objects. I'll have to look for them now. Thanks!

I thank you Quantum for your good work on this tool and also thanks to Knobby for the informative insight on the zone file format.
May I ask you sir, in which archive are the zone files (*.czh_pc and *.czn_pc) located for SRTT ?
I have the full legal Steam version installed in the default location --> C:\Program Files (x86)\Steam\SteamApps\common\saints row the third
Is it possible to remove all the trees and utility poles along with the attached electrical lines for all zones in the free roam mode ?
Have you had any success thus far in editing zones ?

Thanks! I suggest you wait until I release my new XML converter tool before trying to actually change anything. The SRReadZone tool can only display zone files -- not change them. The new tool will import and export an XML file that you can edit with any text editor.

I'd suggest you make a library that can read & write the zone format like I do for my tools, then build apps that use that library. That way it's possible for other people to make applications that use it, it also makes it easier if you need to reuse the same code in several different apps, and it means that you don't have to update code in three different apps - instead you just update one library. Much easier.

That's exactly what I'm doing. I'm building an object oriented library that contains a class for each section, object, property and other data chunks in the file, with reader and writer methods for both binary (zone file format) and XML. And it's designed to be very extensible as we become aware of other data structures that can be parsed. Anyone will be able to use the library to read, access, change, and write the file content. While my original parser (SRReadZone) was just a quick and dirty proof of concept, this code will (hopefully) be a thing of beauty! But, I want to spend the time to do this right with a solid foundation and good architecture that people can work with, so it will take a bit longer. And, well, code comments are always helpful to people -- so I'm trying to be good with that part too.

I deliberately selected C# for the programming language because that's what you are using and I wanted to keep things consistent and compatible. I'm very familiar with C++ and object oriented programming, but not as much with C# so it's a bit of a learning curve. And now I need to learn Git, so it will take be a little time to get everything moved to GitHub, but I know it's the way I want to go.

 

[Minimaul]

That's exactly what I'm doing. I'm building an object oriented library that contains a class for each section, object, property and other data chunks in the file, with reader and writer methods for both binary (zone file format) and XML. And it's designed to be very extensible as we become aware of other data structures that can be parsed. Anyone will be able to use the library to read, access, change, and write the file content. While my original parser (SRReadZone) was just a quick and dirty proof of concept, this code will (hopefully) be a thing of beauty! But, I want to spend the time to do this right with a solid foundation and good architecture that people can work with, so it will take a bit longer. And, well, code comments are always helpful to people -- so I'm trying to be good with that part too.

Awesome

I deliberately selected C# for the programming language because that's what you are using and I wanted to keep things consistent and compatible. I'm very familiar with C++ and object oriented programming, but not as much with C# so it's a bit of a learning curve. And now I need to learn Git, so it will take be a little time to get everything moved to GitHub, but I know it's the way I want to go.

It may well be easier to write these kinds of tools in C or C++ - but I very much like .NET as a programming environment which is part of the reason I stuck with C#. The other reason was that Rick/Gibbed's original tools for SR2 and SRTT were written in C#.

You mentioned in the other thread (the file format one) that the files you'd tried loaded OK. My best recommendation here is to write something that will load every file in the game - that way you can rapidly see if there are any files that don't work rather than just running into them later. When you get to the point of being able to save files, I'd do the same. Write a test tool that loads each zone in turn, parses it, then saves it again. Then pack all of it back up and run the game.

I do exactly this with packfiles & ASM files - I can extract every single packfile in SRIV & SRGOOH then recreate them and the game runs flawlessly afterwards. It's a wonderful way to fish out weird bugs.

 

[Quantum]

It may well be easier to write these kinds of tools in C or C++ - but I very much like .NET as a programming environment which is part of the reason I stuck with C#. The other reason was that Rick/Gibbed's original tools for SR2 and SRTT were written in C#.

Well, although some of it would be easier in C++, I do appreciate the .NET classes such as XmlDocument which makes the XML part a LOT easier! I had already used the .NET XML parser in my Patch Scripts.

It may well be easier to write these kinds of tools in C or C++ - but I very much like .NET as a programming environment which is part of the reason I stuck with C#. The other reason was that Rick/Gibbed's original tools for SR2 and SRTT were written in C#.

You mentioned in the other thread (the file format one) that the files you'd tried loaded OK. My best recommendation here is to write something that will load every file in the game - that way you can rapidly see if there are any files that don't work rather than just running into them later. When you get to the point of being able to save files, I'd do the same. Write a test tool that loads each zone in turn, parses it, then saves it again. Then pack all of it back up and run the game.

I do exactly this with packfiles & ASM files - I can extract every single packfile in SRIV & SRGOOH then recreate them and the game runs flawlessly afterwards. It's a wonderful way to fish out weird bugs.

Actually, that's how I was planning to test this. Read Zone file, Write XML file, Read XML file back, Write Zone file, Compare to original Zone file -- should match exactly! (that's my GOAL anyway)