Soul Reaver to Blender Conversion Toolchain

article by Ben Lincoln

The Soul Reaver to Blender Conversion Toolchain is a collection of modified tools and custom scripts that permits mass-conversion of most of the data from a build of Soul Reaver for use in Blender, the free/open source 3D modeling and rendering suite. It incorporates modified versions of several of Andrew Fradley's tools, include ModelEx and Recombobulator. The version of Recombobulator included in this toolchain is heavily modified from a very early version of Andrew's tool, and not really useful for other purposes. The modified ModelEx has some features I think are handy, and it can also be downloaded separately from the toolchain on the ModelEx page.

Example Images

1999-02-04 - Citadel and Undercity

1999-02-16 - Orrery

1999-02-16 - Turel's Territory

1999-06-10 - Movie6

Example output from the toolchain.

Unlike most of the other software on this site, the toolchain is an expert tool that's more of a box of pieces that can do a lot of different things depending on the way it's configured and used. This page includes some walkthroughs for using it to achieve common tasks, but not every possible output it can generate.

A less manual approach will be described in a future version.

If you don't already have Python installed, head over to python.org and install the current version.

Pick a base directory for all of your toolchain content. These instructions assume you'll be using C:\Legacy_of_Kain.

Make a directory within that called Map_Toolchain, and make one within that named 0.16.

Unpack all of the conversion toolchain content from the download at the bottom of this page into the 0.16 directory.

Make a directory within the base directory named after the build of Soul Reaver you'll be working with. For example, C:\Legacy_of_Kain\PlayStation_NTSC_Release. Make a directory within that called Extracted, and use Soul Spiral to unpack the bigfile from that version of the game into it. When Soul Spiral is done extracting the contents, you should see a directory named kain2 within Extracted, e.g. C:\Legacy_of_Kain\PlayStation_NTSC_Release\Extracted\kain2.

Open a Windows command prompt. If you are using PowerShell, you'll need to run cmd.exe within it, or the commands below won't be interpreted correctly.

cd into your build directory, e.g. C:\Legacy_of_Kain\PlayStation_NTSC_Release, then cd into that new directory.

Run the following command, substituting the full path to your base directory after the =.

set BASEPATH=C:\Legacy_of_Kain

Run the following command, substituting the name you gave your build directory after the =. E.g. if your build directory is C:\Legacy_of_Kain\PlayStation_NTSC_Release, you would run the command set BUILDDATE=PlayStation_NTSC_Release.

set BUILDDATE=YOUR_BUILD_DIRECTORY_HERE

If the version of the game is any of the release versions, run this command:

set DRMTYPE=release

set PORTALOVERRIDE=sr1ps1ntsc

set DRMEXT=.pcm

If it's from 1999-06-01 to 1999-07-14, enter this instead:

set DRMTYPE=beta

set PORTALOVERRIDE=sr1ps1ntsc

set DRMEXT=.pcm

If it's from May, 1999, enter this instead:

set DRMTYPE=beta19990512

set PORTALOVERRIDE=sr1beta19990512

set DRMEXT=.pcm

If it's from 1999-01-23, enter this instead:

set DRMTYPE=alpha19990123

set PORTALOVERRIDE=sr1alpha19990123

set DRMEXT=.drm

If it's from 1999-02-04, enter this instead:

set DRMTYPE=alpha19990204

set PORTALOVERRIDE=sr1alpha19990204

set DRMEXT=.drm

If it's from 1999-02-16, enter this instead:

set DRMTYPE=alpha19990216

set PORTALOVERRIDE=sr1alpha19990216

set DRMEXT=.drm

Run the following series of commands:

REM origin area for world layout

set ORIGINAREA=cliff1

@REM Tools

set MODELEX=%BASEPATH%\Map_Toolchain\0.16\ModelEx5\ModelEx\bin\x86\Release\ModelEx.exe

set MODELEXTEST=%BASEPATH%\Map_Toolchain\0.16\modelex_test_cases.bat

set RECOMBOB=%BASEPATH%\Map_Toolchain\0.16\Recombobulator\Recombobulator\bin\Debug\Recombobulator.exe

set MODELEXCONVERSIONSCRIPT=%BASEPATH%\Map_Toolchain\0.16\generate_modelex_conversion_script.py

set MODELEXCONVERSIONOPTIONS=

If you're converting files from a PC build, run these commands:

REM for PC only:

set MODELEXCONVERSIONOPTIONS=--texture-file "%BASEPATH%\%BUILDDATE%\textures.big"

If you're converting files from a Dreamcast build, run these commands:

REM for Dreamcast only:

set MODELEXCONVERSIONOPTIONS=--dreamcast --texture-file "%BASEPATH%\%BUILDDATE%\textures.vq"

If you want do do the white/red deleted-area highlight style of map, run these commands:

REM for deleted versus not-deleted only:

set MODELEXCONVERSIONOPTIONS=--highlight-deleted

If you want do do the white/green added-area highlight style of map, run these commands:

REM for added/always-present only:

REM set MODELEXCONVERSIONOPTIONS=--highlight-added

Regardless of the type of map you want to build, run these commands:

set JSCONCONVERSIONSCRIPT=%BASEPATH%\Map_Toolchain\0.16\generate_json_conversion_script.py

set POSITIONCALCULATIONSCRIPT=%BASEPATH%\Map_Toolchain\0.16\generate_blender_import_and_arrange_script.py

set LEVELCOMMANDSCRIPT=%BASEPATH%\Map_Toolchain\0.16\make_level_commands.py

set DRMLISTAREAS=%BASEPATH%\%BUILDDATE%\drm_list-areas-%BUILDDATE%.txt

set DRMLISTOBJECTS=%BASEPATH%\%BUILDDATE%\drm_list-objects-%BUILDDATE%.txt

set MODELSDIRAREAS=%BASEPATH%\%BUILDDATE%\AreaModelsMaterial

md "%MODELSDIRAREAS%"

set MODELSDIRAREASSPECTRAL=%BASEPATH%\%BUILDDATE%\AreaModelsSpectral

md "%MODELSDIRAREASSPECTRAL%"

set MODELSDIROBJECTS=%BASEPATH%\%BUILDDATE%\ObjectModels

md "%MODELSDIROBJECTS%"

set MODELEXSCRIPTAREAS=%BASEPATH%\%BUILDDATE%\generate_material_area_collada_files.bat

set MODELEXSCRIPTAREASSPECTRAL=%BASEPATH%\%BUILDDATE%\generate_spectral_area_collada_files.bat

set MODELEXSCRIPTOBJECTS=%BASEPATH%\%BUILDDATE%\generate_object_collada_files.bat

set BLENDERPOSITIONSCRIPTMATERIAL=%BASEPATH%\%BUILDDATE%\blender_import_and_position-material.py

set BLENDERPOSITIONSCRIPTSPECTRAL=%BASEPATH%\%BUILDDATE%\blender_import_and_position-spectral.py

set JSONDIR=%BASEPATH%\%BUILDDATE%\JSON

md "%JSONDIR%"

set JSONSCRIPT=%BASEPATH%\%BUILDDATE%\generate_json_files.bat

REM Build a list of all of the area DRMs for the build

dir /s /b "%BASEPATH%\%BUILDDATE%\Extracted" | find "\area\" | find "%DRMEXT%" | find /v "invalid" | find /v "duplicate" > "%DRMLISTAREAS%"

REM Build a list of all of the object DRMs for the build

dir /s /b "%BASEPATH%\%BUILDDATE%\Extracted" | find "\object\" | find "%DRMEXT%" | find /v "invalid" | find /v "duplicate" > "%DRMLISTOBJECTS%"

REM Export the necessary DRM properties as JSON using the hacked Recombobulator

python "%JSCONCONVERSIONSCRIPT%" --input "%DRMLISTAREAS%" --recombobulator "%RECOMBOB%" --base-output-dir "%JSONDIR%" --output "%JSONSCRIPT%" --filetype "%DRMTYPE%"

If you're converting files from a Dreamcast build, you'll need to follow all of the previous steps separately for the PC version of the game, then copy the JSON directory into the Dreamcast build directory at this time.

Regardless of the build you're working from, execute the following commands:

"%JSONSCRIPT%" > "%JSONDIR%\JSON_Conversion_Log.txt" 2>1

REM Export the material plane version of the area DRMs as Collada files using the hacked ModelEx

python "%MODELEXCONVERSIONSCRIPT%" --input-list "%DRMLISTAREAS%" --modelex "%MODELEX%" --base-output-dir "%MODELSDIRAREAS%" --output "%MODELEXSCRIPTAREAS%" %MODELEXCONVERSIONOPTIONS% --areas

"%MODELEXSCRIPTAREAS%" > "%MODELSDIRAREAS%\ModelEx_Conversion_Log.txt" 2>1

REM Export the spectral plane version of the area DRMs as Collada files using the hacked ModelEx

python "%MODELEXCONVERSIONSCRIPT%" --input-list "%DRMLISTAREAS%" --modelex "%MODELEX%" --base-output-dir "%MODELSDIRAREASSPECTRAL%" --output "%MODELEXSCRIPTAREASSPECTRAL%" %MODELEXCONVERSIONOPTIONS% --areas --spectral

"%MODELEXSCRIPTAREASSPECTRAL%" > "%MODELSDIRAREASSPECTRAL%\ModelEx_Conversion_Log.txt" 2>1

REM Export the object DRMs as Collada files using the hacked ModelEx

python "%MODELEXCONVERSIONSCRIPT%" --input-list "%DRMLISTOBJECTS%" --modelex "%MODELEX%" --base-output-dir "%MODELSDIROBJECTS%" --output "%MODELEXSCRIPTOBJECTS%" %MODELEXCONVERSIONOPTIONS% --objects

"%MODELEXSCRIPTOBJECTS%" > "%MODELSDIROBJECTS%\ModelEx_Conversion_Log.txt" 2>1

If you're generating normal versions of the models/maps, execute these commands:

REM generate a lot of variations on these:

python "%LEVELCOMMANDSCRIPT%" > "%BASEPATH%\%BUILDDATE%\Level_Generation_Commands.bat" --overhead-lights-half-strength

If you're generating the highlight-deleted or highlight-added versions instead, execute these commands:

REM for deleted versus not-deleted:

REM python "%LEVELCOMMANDSCRIPT%" --overhead-lights-half-strength --double-sided-polygons --eevee > "%BASEPATH%\%BUILDDATE%\Level_Generation_Commands.bat"

Examine the contents of the Level_Generation_Commands.bat file, which will contain a large number of possible commands to run, depending on what collection of areas you want to convert into Blender. Pick the one you want, and run it. For example, to convert the entire Material Plane version of the world map:

REM material plane with objects (spincam):

python "%POSITIONCALCULATIONSCRIPT%" "%ORIGINAREA%" --start-area-name %ORIGINAREA% --start-area-file "%JSONDIR%\%ORIGINAREA%.json" --areas-collada-dir "%MODELSDIRAREAS%" --objects-collada-dir "%MODELSDIROBJECTS%" --output "%BASEPATH%\%BUILDDATE%\blender_import_and_position-material.py" --log "%BASEPATH%\%BUILDDATE%\Blender_Import_Debug_Log-Material.txt" --material --import-objects --breadth-first --ignore-raziel --ignore-non-visible --portal-override-list %PORTALOVERRIDE% --place-unlinked-areas --place-objects-simultaneously --overhead-lights-half-strength --place-unused-objects --add-overhead-lights --add-spincam --spin-num-rotations 1 --spin-num-frames 300 --spin-start-height 350 --spin-end-height 350 --spin-start-distance 400 --spin-end-distance 400 > "%BASEPATH%\%BUILDDATE%\Position_Calculation_Log-Material.txt" 2>&1

Open the Python script which was just generated by that command. For example, blender_import_and_position-material.py. Copy and paste its contents into a new script in Blender. I recommend enabling the system console. Run the script. For small areas (such as just the Underworld, it should complete in a few minutes. Very complex collections (such as the complete world map) may take a day or two to finish, because Blender gets increasingly slow with each object which is added to the scene. Sorry. There's not really anything I can do about this.

One the script finishes in Blender, you should be able to work with the model content.

If you want to generate the automated assembly animations like I did, copy and paste the content of the assemble_scene_in_blender.py or assemble_scene_in_blender-spiral_outward.py script into a different script in Blender, and run that.

Download
File	Size	Version	Release Date	Author
ModelEx Prerequisites	23 MiB	1.0	2020-05-12	Various
The installers you'll need for SlimDX and the correct versions of the Microsoft Visual C++ Runtime. On modern versions of Windows, you'll need to install all four packages. If you have a very old, 32-bit version of Windows, you don't need to install the 64-bit packages. You only need to install the packages once on a given computer, regardless of how many versions of ModelEx you're using on it.

Download
File	Size	Version	Release Date	Author
Soul Reaver to Blender Conversion Toolchain	55 MiB	0.16	2020-05-12	Ben Lincoln
Source is included for the binary tools.