Modding tools

[emoose]

Since things are a bit scattered atm it'd probably be good to start a thread for any useful tools, feel free to link any other tools here too or discuss about how to mod the game.

General tools

• offzip - can be used to decompress most of games .SZ files via mkdir output; offzip -a filename.sz output (some SZ files might not decompress properly though, not really sure why)
• 010 Editor - great hex editor, can use templates that give names/structures to the bytes in a file rather than needing to stare at hex digits all day, lots of templates available for common file types too.
• procmon - can be used to see what files / IP addresses that the game tries to access
• Cheat Engine 7.5 - can inspect memory addresses & also mess with the games code, the ad-free/malware-free version is linked, to install it properly run the following using command-prompt CheatEngine75.exe /VERYSILENT /ZBDIST

OutRun2 tools

• OR2Tool 0.1.3 by emoose - tool for unpacking/repacking C2C SZ files, right now it can extract sprite SZ files into dds files & XML for the atlas info, and also repack updated atlas back to SZ, maybe PMT model support in future as well.
• or2-tools (JayFoxRox) - Python scripts for working with several file formats, seems mostly built for OR2 Xbox but some support for C2C is added
• or2-tools (Sonic-TV) - fork of the above, I think C2C support is meant to be improved but the repo currently matches JayFoxRox version, hopefully update soon
• OutrunX v2.2 by Howard - tool that can use offzip to decompress & then split DDS files from some SZ files (though some SZ's contain textures that are missing DDS headers, which this won't work with - OR2Tool should work for those fine)
• OR2 010 Editor templates - detailed templates for the games sprite/model files that can be loaded into 010 Editor
• FXTCourseEdit v1.0 by Howard - allows editing the courses in the game

Other

• "The Beautiful Game: Inside OutRun 2006: Coast 2 Coast" - interview with some of the Sumo Digital team that worked on C2C, some interesting info about how the game works there

[envido32]

Oh this is truly amazing, thank you so much! This is so handy!

btw, there was a newer OutrunX v2.2 than the link you shared.

And not exactly a tool but there was a Course Editor in development at one point, I think this is the only alpha release available but it's still interesting to test.

[Tenome]

The course editor is fun, unfortunately it doesn't support hacking in 15+15 courses for the true endurance test since I think you'd have to change the level table to support that as well.

Has anyone looked into extracting/modifying the SFX?

[Tenome]

Are the flags for hitting checkpoints easy to find? I might want to try and make a LiveSplit for AutoSplitter later, which requires finding the memory addresses to watch.

[envido32]

Are the flags for hitting checkpoints easy to find? I might want to try and make a LiveSplit for AutoSplitter later, which requires finding the memory addresses to watch.

I just tested CheatEngine for the fist time with Howard's CT files and to be honest is much more than I can chew...

But it seems to be hidden here somewhere

[Tenome]

Damn, I wished I checked Github first lol. I just wasted two hours scanning trying to find the value, thinking it might be a unique flag that was calculating the time difference, when I could have just used that CT table which already has what I think I need ("stages passed" and "actual stage number" that simply go up by one). Oh well, at least I was getting through my backlog of music the entire time and found some more songs to add to the CD switcher.

Edit: Hm, it's a start. Hitting the last goal doesn't actually increase it, though, so I have to figure out what to do with that. I'm trying to lock the timer and see which value the "Time Elapsed" address (007D39DC 4 byte) equals the checkpoint time, but I can't seem to actually freeze the timer when I check it off. It's always increasing by a split second before snapping back down to the value I set.

[envido32]

Damn, I wished I checked Github first lol. I just wasted two hours scanning trying to find the value, thinking it might be a unique flag that was calculating the time difference, when I could have just used that CT table which already has what I think I need ("stages passed" and "actual stage number" that simply go up by one). Oh well, at least I was getting through my backlog of music the entire time and found some more songs to add to the CD switcher.

Edit: Hm, it's a start. Hitting the last goal doesn't actually increase it, though, so I have to figure out what to do with that. I'm trying to lock the timer and see which value the "Time Elapsed" address (007D39DC 4 byte) equals the checkpoint time, but I can't seem to actually freeze the timer when I check it off. It's always increasing by a split second before snapping back down to the value I set.

If you have more experience with CE Howard left a lot of useful information in that threat, from page 26 to 29 he explains how he found the stages files, made a lookup table and how they are connected. He event talks about what type of bugs or limitations he stumble-upon, very interesting stuff.

I wish I'll be able to give it a use soon, but my technical level is years behind. The track editor randomize sounded amazing to try but it seems that it was never released as far as I'm aware :(

[emoose]

OR2Tool 0.1.2: OR2Tool-0.1.2.zip

• Hopefully fixed issue with exported DDS files not being padded out, which stopped texconv working with them
• Adds support for exporting JSON atlas files which can be opened in Atlased.

texture_X_atlas.json files will be exported to same folder as info.xml/texture_X.dds/etc.

You'll need to convert the DDS texture to png first (texconv -ft png texture_X.dds) and then flip it vertically, after that Atlased should be able to load the texture_X_atlas.json file for you.

~~There's no support for reading in updated atlas JSONs yet~~ (added in 0.1.3 below), but the sprite_XXX numbers shown in Atlased do match the XML's <Sprite Index="XXX">, so you could update the XML yourself using the values from Atlased (note that XML expects end X/Y, not size which Atlased shows - just add the position + size from Atlased to get the end)

[emoose]

OR2Tool 0.1.3: OR2Tool-0.1.3.zip

• Will now try to convert DDS to PNG & flip it vertically automatically, so you can just extract the XST and then load JSON straight into Atlased - hopefully the decoders are right for all the formats, if you notice any broken PNG with it please let me know.

• Now reads in json atlas files when updating the XST, so you can use Atlased to edit the atlas & save your changes now

Just use the normal commands to extract the XST and then update it from the XML, eg.

1. Run or2tool spritefile_xst.sz to extract to spritefile folder (or drag+drop the xst into or2tool)
2. update XML/JSON files inside there
3. or2tool -xml spritefile\info.xml -o C:\Games\OR2006\Sprites\spritefile_new_xst.sz spritefile_xst.sz to update it, any JSON files that exist next to info.xml should also get read in.

Would probably be possible to let the game itself read in updated JSON atlas files as well, so we wouldn't have to share modded .sz files around - if there's still interest in atlas modding I can see if we can add something for that.

[Sonic-TV]

I guess atlas modding is kinda needed for multilingual texts. Some of the texts are just squeezing for fitting in the atlases. (Example: "position" on vs mode has a narrower spacing comparing to other texts.)

[Tenome]

We learned that if you use FXT Course Editor to make a custom mixed (2 + SP + Reversed) layout, vanilla players can still join the lobby and run the intended tracks (with the exception of Dusk/Night stages, which get switched to their daytime variants). However, the vanilla players will disappear from the modded players and vice versa when they change to the next track. Something to keep in mind if we ever get official custom track order support down the line. I believe Howard was working on that for his next FXT Editor update, which would have put a new menu for each custom track order in the in-game menu.

[emoose]

Kinda got texture extraction working for Online Arcade, mostly matched C2C texture format but they switched some Xbox structs to X360 ones, and also used X360 tiled swizzling too...

Sadly haven't found any textures that are actually higher res than C2C yet, maybe there's some that are less crispy though, I'll see if I can push a OR2Tool update for it soon.

I've only really looked at UI sprites though, maybe stage textures could have some improvements, has anyone noticed anything better quality in OA? IIRC S0L did mention it could have some things, maybe he meant the car models/shaders though.

[Sonic-TV]

I guess you can add supports for GZ files used in SDX now...

[emoose]

Looks like SDX GZ are normal gzip files but with a 0xB header "or2 2099304 " / 6F 72 32 20 32 30 39 39 33 30 34 20 If you delete those 0xB bytes, you can use "gzip -d spr_XXX.gz" to decompress to spr_XXX file Then to recompress you can use "gzip -k spr_XXX" to create spr_XXX.gz, then add those 0xB bytes to the beginning

Maybe will see if I can add extraction support to or2tool for them soon

[Sonic-TV]

Looks like SDX GZ are normal gzip files but with a 0xB header "or2 2099304 " / 6F 72 32 20 32 30 39 39 33 30 34 20 If you delete those 0xB bytes, you can use "gzip -d spr_XXX.gz" to decompress to spr_XXX file Then to recompress you can use "gzip -k spr_XXX" to create spr_XXX.gz, then add those 0xB bytes to the beginning

Maybe will see if I can add extraction support to or2tool for them soon

Thanks. Or you can make the tool pack the sprites in XST format as they are just pure XSTs inside of them.

[Tenome]

OR2Tool 0.1.3: OR2Tool-0.1.3.zip

Has anyone tried scaling the json's expected coordinates to accommodate larger spritesheets to make alignment easier? Can I just multiply them?

[Sonic-TV]

bugs here: if you extract SZ files in Outrun Online Arcade, the following error occurs. (Version 0.1.3) D:\Outrun Online Arcade\X360-ALL>or2tool .\sprite\spr_SPRANI_CLAR_RANK_Fxst.sz Decompressing XST... Reading XST... Unhandled exception. System.ArgumentOutOfRangeException: count ('-1572864') must be a non-negative value. (Parameter 'count') Actual value was -1572864. at System.ArgumentOutOfRangeException.ThrowNegative[T](T value, String paramName) at System.IO.BinaryReader.ReadBytes(Int32 count) at OutRun2Tool.XST.Read(IO io) at OutRun2Tool.Program.Main(String[] args)

[emoose]

Yeah arcade uses slightly diff format, did get something working for it at https://github.com/emoose/OutRun2006Tweaks/issues/90#issuecomment-2308370823 but changing code broke it for PC, I'll see if I can add some OA mode to it soon.

IIRC the textures weren't much different to PC though, at least the UI sprites anyway, not sure if track/car textures might have been changed.

[Sonic-TV]

Yeah arcade uses slightly diff format, did get something working for it at #90 (comment) but changing code broke it for PC, I'll see if I can add some OA mode to it soon.

IIRC the textures weren't much different to PC though, at least the UI sprites anyway, not sure if track/car textures might have been changed.

I'll wait then. Can your tool extract XMTs and BINs(used on models and courses), btw?

[nhasa01]

Is it possible to add more elements ingame? I wanted to add more Ferrari cars but without taking away the ones that already exist in the game. I would also like to add more country flags without removing the ones that already exist in the game, as I have just changed the flag of Thailand to add the flag of my Brazil. It would be nice to be able to add the flags of all the countries in the world. Another question... Is it possible to implement an offline multiplayer split-screen mode up to 4, 6 or even 8 cars? It could be awesome play with other 6 or 7 friends on my 70" TV!

[Tenome]

Actual modding is outside the scope of Tweaks, we won't be getting any new cars, etc.

[Zoukambada]

Convert Atlas.json to SVG

It would be interesting if we had a tool that could convert exported OR2 atlas (like for example: BF3EE5C6_512x512_atlas.json) to a SVG vector image with the same dimensions with its rectangle areas. It would be easier to remaster textures with precision. I'm doing by hand using Atlased tool and getting its parameters and drawing them in InkScape / Illustrator.

This is what I'm doing:

I tried to automate the process creating a script, but as I'm not a developer I couldn't get it working. I worked with the AI Gemini from Google and it generated this script "atlas2svg.ps1", a Windows PowerShell Script:

# OutRun2006Tweaks Convert Atlas.json to SVG Windows PowerShell Script
# atlas2svg.ps1 - Version 1.2 - 20241217

# Instructions
# 1) Navigate to the directory where the script and your JSON file are located.
# 2) Execute the script with the JSON file name as an argument:
# 3) .\atlas2svg.ps1 HASHID_WITDHxHEIGHT_atlas.json

# Attempt to load System.Management.Automation module 
Import-Module Microsoft.PowerShell.Management -Force # Might require administrator privileges

# Get the JSON file name from the command line argument
$jsonFile = $args[0]

# Extract dimensions and base name from the filename
$filenameRegex = '^(.+?)_(\d+)x(\d+)_atlas\.json$'
$match = $jsonFile -match $filenameRegex

if ($match) {
  $width = $matches[2]
  $height = $matches[3]
  $baseName = $matches[1]

  # Get the directory path of the JSON file
  $jsonDir = Split-Path $jsonFile

  # Check if directory path is valid
  if ($jsonDir) {
    $svgFile = Join-Path $jsonDir "$baseName.svg"
    Write-Host "Saving SVG to: $svgFile"
  } else {
    Write-Warning "Unable to determine output directory. Using current directory."
    $svgFile = "$baseName.svg"
  }
} else {
  Write-Warning "Invalid filename format. Please use HASHID_WITDHxHEIGHT_atlas.json"
  exit 1
}

# Use ConvertFrom-Json to parse the JSON data
$jsonData = ConvertFrom-Json -InputObject (Get-Content $jsonFile)

# Create a new SVG file
$svg = New-Object System.Xml.XmlDocument
$svg.AppendChild($svg.CreateElement("svg"))
$svg.DocumentElement.SetAttribute("width", $width)
$svg.DocumentElement.SetAttribute("height", $height)
$svg.DocumentElement.SetAttribute("xmlns", "http://www.w3.org/2000/svg")

# Add rectangles to the SVG (modify based on your JSON data structure)
foreach ($region in $jsonData.regions) {
  $rect = $svg.CreateElement("rect")
  $rect.SetAttribute("x", $region.rect[0])
  $rect.SetAttribute("y", $region.rect[1])
  $rect.SetAttribute("width", $region.rect[2])
  $rect.SetAttribute("height", $region.rect[3])
  $rect.SetAttribute("fill", "blue")  # Adjust fill color as needed
  $svg.DocumentElement.AppendChild($rect)
}

# Save the SVG file
$svg.Save($svgFile)

After running the script in the same path as the JSON through Windows PowerShell like this: ".\atlas2svg.ps1 HASHID_WITDHxHEIGHT_atlas.json"

1. It would detect the filename and it would define the SVG artboard dimensions from it;
2. then it would get the rectangle objects with its dimensions and coordinates, and draw them into a SVG file;
3. This file would have the same name as the JSON but with the SVG extension, in the same path where the JSON is located.

The problem is I got lots of errors, I tried to manipulate the fixes with Gemini and event then it couldn't fix the script. I tried to run it with Administrator privileges in Windows 10 FYI. Does someone have the knowledge to fix this script our make a better tool?

The JSON that I'm using to test the script was downloaded from https://github.com/Sonic-TV/OR2006Sprites/ BF3EE5C6_512x512_atlas.json

[envido32]

Convert Atlas.json to SVG

It would be interesting if we had a tool that could convert exported OR2 atlas (like for example: BF3EE5C6_512x512_atlas.json) to a SVG vector image with the same dimensions with its rectangle areas. It would be easier to remaster textures with precision. I'm doing by hand using Atlased tool and getting its parameters and drawing them in InkScape / Illustrator.

This is what I'm doing:

I tried to automate the process creating a script, but as I'm not a developer I couldn't get it working. I worked with the AI Gemini from Google and it generated this script "atlas2svg.ps1", a Windows PowerShell Script:

# OutRun2006Tweaks Convert Atlas.json to SVG Windows PowerShell Script
# atlas2svg.ps1 - Version 1.2 - 20241217

# Instructions
# 1) Navigate to the directory where the script and your JSON file are located.
# 2) Execute the script with the JSON file name as an argument:
# 3) .\atlas2svg.ps1 HASHID_WITDHxHEIGHT_atlas.json

# Attempt to load System.Management.Automation module 
Import-Module Microsoft.PowerShell.Management -Force # Might require administrator privileges

# Get the JSON file name from the command line argument
$jsonFile = $args[0]

# Extract dimensions and base name from the filename
$filenameRegex = '^(.+?)_(\d+)x(\d+)_atlas\.json$'
$match = $jsonFile -match $filenameRegex

if ($match) {
  $width = $matches[2]
  $height = $matches[3]
  $baseName = $matches[1]

  # Get the directory path of the JSON file
  $jsonDir = Split-Path $jsonFile

  # Check if directory path is valid
  if ($jsonDir) {
    $svgFile = Join-Path $jsonDir "$baseName.svg"
    Write-Host "Saving SVG to: $svgFile"
  } else {
    Write-Warning "Unable to determine output directory. Using current directory."
    $svgFile = "$baseName.svg"
  }
} else {
  Write-Warning "Invalid filename format. Please use HASHID_WITDHxHEIGHT_atlas.json"
  exit 1
}

# Use ConvertFrom-Json to parse the JSON data
$jsonData = ConvertFrom-Json -InputObject (Get-Content $jsonFile)

# Create a new SVG file
$svg = New-Object System.Xml.XmlDocument
$svg.AppendChild($svg.CreateElement("svg"))
$svg.DocumentElement.SetAttribute("width", $width)
$svg.DocumentElement.SetAttribute("height", $height)
$svg.DocumentElement.SetAttribute("xmlns", "http://www.w3.org/2000/svg")

# Add rectangles to the SVG (modify based on your JSON data structure)
foreach ($region in $jsonData.regions) {
  $rect = $svg.CreateElement("rect")
  $rect.SetAttribute("x", $region.rect[0])
  $rect.SetAttribute("y", $region.rect[1])
  $rect.SetAttribute("width", $region.rect[2])
  $rect.SetAttribute("height", $region.rect[3])
  $rect.SetAttribute("fill", "blue")  # Adjust fill color as needed
  $svg.DocumentElement.AppendChild($rect)
}

# Save the SVG file
$svg.Save($svgFile)

After running the script in the same path as the JSON through Windows PowerShell like this: ".\atlas2svg.ps1 HASHID_WITDHxHEIGHT_atlas.json"

1. It would detect the filename and it would define the SVG artboard dimensions from it;

2. then it would get the rectangle objects with its dimensions and coordinates, and draw them into a SVG file;

3. This file would have the same name as the JSON but with the SVG extension, in the same path where the JSON is located.

The problem is I got lots of errors, I tried to manipulate the fixes with Gemini and event then it couldn't fix the script. I tried to run it with Administrator privileges in Windows 10 FYI. Does someone have the knowledge to fix this script our make a better tool?

The JSON that I'm using to test the script was downloaded from https://github.com/Sonic-TV/OR2006Sprites/ BF3EE5C6_512x512_atlas.json

Done!

I made a simple Python3 script that reads the atlas.json and makes the .svg files

You can find the script it here:

https://github.com/Sonic-TV/OR2006Sprites/blob/main/Original%20(PC)/json2svg/json2svg.py

And the generated SVGs on the Sonic-TV Textures PC dump folders, here is an example:

https://github.com/Sonic-TV/OR2006Sprites/blob/main/Original%20(PC)/Original%20(Tweaks%20dumps)/spr_sprani_game_cvt_Exst/36895E6C_256x512.svg

[Zoukambada]

Thank you @envido32 ! This worked flawlessly with the texture that I was working on! Finally I can check precisely if the sprite is fitting properly at his boundaries.

[Darktreivor]

@emoose can you help me to understante texture in C2C ps2 version? I extract the sprit and decompress .sz files, but i try extract texture usando OR2tool nothing happend. I'm localizing this game for Brazilian Portuguese.

bloco_33_unpack.zip