Home > Software > Soul Reaver to Blender Conversion Toolchain
Soul Reaver to Blender Conversion Toolchain
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 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 =.
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.
If the version of the game is any of the release versions, run this command:
If it's from 1999-06-01 to 1999-07-14, enter this instead:
If it's from May, 1999, enter this instead:
If it's from 1999-01-23, enter this instead:
If it's from 1999-02-04, enter this instead:
If it's from 1999-02-16, enter this instead:
Run the following series of commands:
REM origin area for world layout
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:
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:
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.
|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.|
|Soul Reaver to Blender Conversion Toolchain||55 MiB||0.16||2020-05-12||Ben Lincoln|
|Source is included for the binary tools.|