Insurgency: Sandstorm

Insurgency: Sandstorm

Create and share custom maps, gamemodes and mutators for Insurgency: Sandstorm.

Learn more and find the game on Steam, Homepage, New World Interactive, Community Discord.

Porting From Source

This is a loose and rough guide (mostly thoughts and code) to extract Source game (Day of Infamy, Insurgency, ...) resources, importing Source maps into Blender for editing, and exporting Source maps from Blender as use in Sandstorm mods.

2 comments

Posted by on


Porting From Source

This is a loose and rough guide (mostly thoughts and code) to:

  • extracting Source game (Day of Infamy, Insurgency, ...) resources
  • getting Source maps into Blender for editing
  • exporting Source maps from Blender as FBX to use in Sandstorm

The pipeline is essentially: BSPSource -> Blender (with the io_import_vmf addon) -> Unreal (the Sandstorm Editor).
Powershell scripts to automate some tedious steps in the this pipeline are included.

PLEASE NOTE: A section on the Blender to Unreal import process and fixes (map collision) has not been added yet. This is on the TODO list.

Computer Resource Recommendations:

  • 8GB+ RAM (the more, the better)
  • 8+ logical processor cores (more the better; shaders can take forever to compile with less than 8 cores)
  • an SSD where your working files reside (NVME preferred)

You can probably get by with lower specs, but Blender and Unreal can be resource hogs!

If you'd prefer to watch a great tutorial where most steps are described, check out: Youtube.com

If you have an issue with any steps in this guide, please reach out to the community on the Insurgency: Sandstorm discord!
Specifically, please post in the porting-from-source channel under Modding:

discord chan

Software Requirements:

  • BSPSource -- decompiles .BSP map files to .VMF files
  • Blender v2.8+ -- imports .VMF files via the io_import_vmf addon and can export as FBX
  • io_import_vmf -- ^
  • a Windows 7+ system
    • Feel free to have a go on Linux or macOS though, however io_import_vmf won't export props and some script code won't work without modification
  • (optional) gcfscape 1.8.6 -- extract models, sounds, materials, etc. from Source game packs (.VPK files)

Installing BSPSource:

  1. Open Github.com in your preferred browser and download "bspsrc_1.4.0.zip" or later.
  2. Extract the contents of the downloaded .zip file to your working directory. Let's extract it to C:\Modding\Source\tools for the sake of this tutorial.
  3. Ensure C:\Modding\Source\tools\bspsrc_1.4.0\bspsrc.jar exists after extraction

Installing Blender

  1. Open Blender.org in your preferred browser and download the installer for your operating system
  2. Run the installer to install Blender ;)

Installing io_import_vmf

  1. Please follow the official io_import_vmf Installation Guide and Configuration Guide
  2. After the steps defined in the Configuration Guide, we need to ensure we've entered the path to all valid *_dir.vpk files that our game may use under "Game VPK archives".

    As an example, Day of Infamy uses multiple folders (doi and doi/content), which I've defined below to ensure io_import_vmf can find all props defined in the maps we import:

    io import vmf doi config

Extracting Source Game Resources

You could follow one of many GCFScape tutorials on Youtube, such as this one: Youtube.com

Unfortunately, we're far too lazy (read "efficient") to spend our time manually extracting all models with the GCFScape, so we'll use the power of Auuutooomatttionnn!

derpyess

The below is a Powershell script to recurse through our chosen folder, find all valid VPK files, and extract the resources from these VPK files to our chosen export directory (.\exports by default).
Our chosen folder can be the root of a specific Source game or a Steam Library path to extract resources from all Source games installed:
Extract-SourceGameResourcesWithGCFScape.ps1

This script automates the opening of VPK files, clicking around in GCFScape, hitting export, then doing that all over again and again and again and again ...

Note for new Powershell users:
If you receive an error about script execution being denied, try setting your script execution policy to "Bypass":
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

The below example will extract all game files from any Source game it can find (mods for those games as well) You'll want to change the path to the steam directory if yours is different. You may also provide multiple paths separated by a comma if you have numerous Steam library paths.

Below is an example of the script which will extract all models, materials, etc... from Day of Infamy (where the script above was saved as "Extract-SourceGameResourcesWithGCFScape.ps1" and we're running the below command in a Powershell window):

.\Extract-SourceGameResourcesWithGCFScape.ps1 -GCFScapePath "C:\Modding\Source\tools\gcfscape186\x64\GCFScape.exe" -SourceGamePath "D:\SteamLibrary\steamapps\common\dayofinfamy"

Once the above finishes, you should have a folder at the following path ".\exports\root" containing all extracted game resources:

gcfscape extracted content

Converting Extracted OGG files to WAV

Assuming we'd like to convert all OGG files to WAV in a specific directory, we can run the following script:
Convert-OggToWavRecursive.ps1

The -Path parameter should be the directory containing extracted OGG files (C:\Modding\Source\scripts\exports in our example) after following the Extracting Source Game Resources section.
To convert all the OGG sound files we extracted to WAV (for use in wwise), we can run the following (assuming the script above was saved to .\Convert-OggToWavRecursive.ps1):

.\Convert-OggToWavRecursive.ps1 -Path "C:\Modding\Source\scripts\exports\root\sound"

Decompiling BSP map files to VMF

To import Source game maps into Blender (using io_import_vmf), we need to decompile the BSP map files to VMF.

The below Powershell script will find all BSP files in the specified directory, decompile them using BSPSource, then move the decompiled files (.vmf and its resources folder) to the specified output directory (.\maps by default):
Decompile-BSPFilesToVMF.ps1

Here's an example of how we can run this script (in a Powershell window):

.\Decompile-BSPFilesToVMF.ps1 -SteamLibraryPaths "C:\Program Files (x86)\Steam\steamapps\common\dayofinfamy"

Once the command above completes, you'll be able to find all the maps BSPSrc was able to successfully decompiled in the .\maps folder:

decompiled maps

Now that we have some VMF map files, we can import each VMF into Blender.

Note that if you're exporting as an FBX to use the map in Insurgency: Sandstorm, you'll need to fix a few issues.

  1. Materials are too shiny!
    • We need to decrease specular, metallic and increase the roughness of many materials
  2. The materials don't show up in Unreal!
    • This is likely due to path separators (/) in material names. If we replace / with _ in each material name, we should be able to solve this.
  3. The Skybox is too tiny!
    • io_import_vmf has a button under "Object" called "Transform VMF 3D Sky" you can use (after selecting the skybox) to fix this. Please check out this video: Youtu.be where the fix is shown.
  4. Some props didn't import!
    • 1 or 2 props not importing is relatively common -- but you should consider following the steps in the Fixing Potential io_import_vmf Prop Import Errors section if you receive 10+ prop import errors. The issue may just be missing VPK files, which contain these props.

Rather than manually solving these issues, we can create a script to fix as many as possible to save us the headache of repetitive tasks.
To cut down on manual importing and fix issues #1 and #2, we can run this script:
Blender-VMF-To-Blend.ps1

Assuming we have the dog_red_d.vmf file at the path below (retrieved via the steps defined in the Decompiling BSP map files to VMF section), the below command will import the map into Blender, fix issues #1 and #2 described above, save the Blender project as a .blend in the

.\Blender-VMF-To-Blend.ps1 -VMFPath "C:\Modding\Source\scripts\maps\dog_red_d.vmf"

Fixing Potential io_import_vmf Prop Import Errors

We likely forgot to add a .VPK containing the props our map uses.

Before learning DoI has two folders containing VPK files (talked about in the Installing io_import_vmf section), I ran the below process to extract all files from all the Source games I had installed, packed them into a "multi-VPK" (one main VPK ending with _dir.vpk), then added this VPK to the Game VPK archives section in the io_import_vmf preferences (mentioned in the Installing io_import_vmf section).

I also defined the path of "just_useful_dir.vpk", a VPK containing all extracted materials, models, sounds, etc., of all source games I own.

This is all probably unnecessary, and I wouldn't recommend trying it first, as extracting all resources from all source games can take a bit of time.

If you do receive import errors for multiple props (10+) upon importing a .VMF, I recommend trying the following steps:

  1. Run the Powershell script found in the Extracting Source Game Resources section to extract your chosen games' resources.
  2. Copy the resources you'd like to pack the VPK into a folder, so we're not packing all extracted resources. The copied resource folders should be at least maps, models, textures, or materials.
  3. Pack all extracted resources with vpk.exe (which comes with Day of Infamy and some other Source games)
    In the example below, I copied the extracted maps, materials, and models folders from export\root into a new folder: C:\Modding\Source\scripts\exports\just_useful
    packing extracted resources
    When vpk.exe is finished packing, (and assuming you used the folder name just_useful) you should have at least one .vpk beginning with just_useful_.
    The VPK we want to add in the Game VPK archives section is the VPK ending with _dir.vpk, just_useful_dir.vpk.

2 comments

Join the community or sign in with your gaming account to join the conversation:

WintorOperator
WintorOperator @wintoroperator

not all heros wear capes

nop_from_insurgency
nop_from_insurgency @nop-from-insurgency

lol xD