Soulstruct for Blender

This Blender add-on enables you to import and export a large number of different FromSoftware file formats.

It's powered by Soulstruct, my giant Python library of FromSoftware formats, and Soulstruct Havok, an experimental expansion library.

I developed these tools over the years in parallel with the development of Dark Souls: Nightfall, and finally put aside some time to polish and release them. I hope they serve you well and anticipate whatever mods they enable :)

Blender 4.1 or later is required. Earlier Blender versions use Python 3.10 (released in 2021), which I sadly do not have the bandwidth or inclination to support any longer in Soulstruct. Surface vertex normal handling was also greatly improved in Blender 4.1, making FLVER import/export significantly easier.

Older releases (<=1.9.3) are still available in the Releases section, which support Blender versions all the way back to 3.7, but lack many features and are no longer updated.

Table of Contents

• Game Support
• Other Features
• Installation
• Basic Usage
• Format Information
• FLVER Models
• Map Collision Models (HKX)
• Navmesh Models (NVM)
• Navmesh Models (NVMHKT)
• Navigation Graph (MCG)
• Animations (HKX)
• Map Placement Files (MSB)
• Known Issues
• Bug Reporting

Game Support

• ✔️ Full: Import and export support.
• ⚠️ Partial: Partial support (e.g. import only, worse material handling, or untested).
• ❌ None: No support (yet).

Other Features

• MCG graph files from Demon's Souls and Dark Souls can be imported as Navigation Graph Collections and can even be fully generated from scratch using the loaded MSB Navmesh parts and models from an MSB.
• MCP navmesh box files that go along with these MCGs are automatically generated when the MSB is exported, as their contents must match the MSB Navmesh parts and bake in their transforms.
• NVMHKT Havok navigation mesh files can be imported and viewed for Elden Ring, but not exported.

I hope to eventually turn most remaining ⚠️ and ❌ symbols in the above table into ✔️ symbols, but it's hard work -- especially support for huge modern MSB files and Havok formats. If there's one feature that you want to see soon, I'm happy to consider it as a commission (which is how Demon's Souls support was added).

However, before you ask, it's unlikely that Collision export support will expand much further. Havok's collision physics system changed radically in 2014 (Bloodborne onwards) and I don't have the tools (or expensive Havok SDK) to be able to regenerate the bounding volume tree structures in these newer files (hkcd and hknp Havok classes). I may eventually add import support so you can at least view the collision meshes in Blender, though.

Installation

This is an experimental add-on that is not yet published to Blender. To install the add-on manually, follow these steps:

1. Ensure you have Blender 4.1 or later, as Python 3.11 is required.
2. Download the add-on .zip file from the GitHub repository (Releases).
3. Unzip the contents into your Blender's user scripts/addons directory.
4. On Windows, the directory is typically at C:/<User>/AppData/Roaming/Blender Foundation/Blender/<version>/scripts/addons/.
5. Do not unzip the contents into the Blender installation directory (e.g. in Program Files). The Soulstruct module may not have write access there. If you see a PermissionError when trying to enable the add-on in Blender, check you haven't done this!
6. Open Blender and go to Edit > Preferences > Add-ons.
7. In the Add-ons tab, find Import-Export: Soulstruct and enable it by checking the box next to it.
8. If you see an error, particularly one about soulstruct module import, double check that io_soulstruct_lib is installed in the scripts/addons directory next to io_soulstruct.
9. Press the N key in the 3D View window or click the little arrow in the top-right and you should see many new tabs including FLVER, Animation, and so on.

If you would like to install or update the add-on directly from Git without an official GitHub release, clone and update (or just download) the repo, and update the contents of scripts/addons/io_soulstruct from the main io_soulstruct folder in the repo.

Note that updated io_soulstruct versions without zip releases may also use newer versions of soulstruct and soulstruct-havok that need to be installed into scripts/addons/io_soulstruct_lib. I'll eventually add these as Git submodules to the repo. (You can update io_soulstruct_lib/soulstruct yourself using the Soulstruct repo, but as soulstruct-havok isn't public yet, this will be impossible to update.)

Whenever you update an add-on in Blender, you will need to either restart Blender (recommended) or call the Reload Scripts function from Blender.

Add-ons directory (you may have other add-ons and files here, like I do):

Add-ons tab in Blender Preferences, after searching for 'Soulstruct':

Basic Usage

The add-on implements many different operators for importing and exporting supported file types. These can be accessed in the new menus on the right of the 3D View.

The add-on also defines new Blender Object subtypes for the FromSoft file types supported by Soulstruct. You can see the subtype (if any) of the currently active Object at the bottom of the General Settings tab. (You can also theoretically modify its subtype here, but usage of this would be rare and require lots of other steps.)

NOTE: Blender uses a vertical Z axis and a right-handed coordinate system, while FromSoft games use a vertical Y axis and a left-handed coordinate system. Soulstruct will automatically convert between these systems when importing and exporting 3D positions and rotations. You should never need to worry about it when just working inside Blender, but keep it in mind, as copy-pasting 3D coordinates/rotations from raw FromSoft data or other applications like DSMapStudio will require you to do the transformations yourself. To transform between FromSoft and Blender positions and rotations, follow these rules (noting that they work in both directions): - For positions, just swap Y and Z. No negation. - For rotation Euler angles, swap Y and Z, then negate all three components.

If an Object has a Soulstruct subtype, that subtype's properties will be exposed in a new Panel in the Object Properties window:

File import/export is handled using a Game directory and a Project directory, both of which can be set in General Settings. The Game directory is the root directory of a game installation (containing the EXE or BIN) and the Project directory should be a directory that mimicks the structure of the Game directory.

Many import operators will automatically find all relevant files in either the Game or Project directory (depending on which is defined and whether Prefer Import from Project is enabled) and offer a convenient choice of file to import. Many export operators will automatically export files to the selected Project directory if given (and the Game directory, if Also Export to Game is enabled). Some of these operators also require a current Selected Map, which should have format m??_??_??_?? and correspond precisely to a folder inside the 'map' subdirectory of the Game/Project directory. You can edit the name of this map directory, or use one of the buttons provided to choose an existing folder name from the Game or Project.

Format Information

FLVER Models

The core FLVER object is represented by a Blender Mesh Object. For simple static FLVERs such as Map Pieces, the Mesh and its Blender materials may hold all necessary data. However, for other FLVERs that support animations (or Map Pieces that use FLVER bones as a way to offset certain groups of vertices), the Mesh Object will be a child of a Blender Armature Object that holds the FLVER bones and controls the Mesh through weighted vertex groups. - For static Map Piece FLVERs, each vertex must be weighted to exactly one bone. - For animated FLVERs, each vertex must be weighted to between one and four bones.

This is done through Blender vertex groups that match the name of one of the bones in the Armature (see the Data Panel in the mesh's Object Properties window). If you're in Edit Mode on this Mesh, you can use the Data Panel to select vertices in groups or re-assign them. Unfortunately, it's not straightforward to tell how many different bones a vertex is weighted to (i.e. how many groups it appears in), but Soulstruct will report the index of any vertex illegally weighted to no bones or more than four bones (or more than one bone for Map Pieces).

NOTE: Every FLVER file needs at least one bone, including static Map Pieces. If this bone is at the origin and has no non-default properties (and the FLVER has no Dummies), Soulstruct will not bother creating an Armature parent when that FLVER is imported as long as the Omit Default Bone option is enabled, and will instead just re-create that default bone, and weight all vertices to it, when the Mesh-only FLVER is exported.

If a FLVER has any Dummies -- arbitrary points in the model that can be used for various purposes like sound effects, visual effects, hitboxes, and event scripting commands (also known by names like 'Model_dmy', 'dummy poly', or 'damipoly'-- these will also be children of the FLVER Armature (which will always be created if any Dummies are present) next to the Mesh. Dummies are a new Soulstruct subtype of Empty Objects in Blender and have several properties that can be set in the FLVER Dummy Properties Panel in the Object Properties window. Some info: - They are usually parented to a specific bone in the Armature, known as the 'attach bone', which is the bone followed by the Dummy during animations. This can be seen in the Relations Panel in the Object Properties. - They also may have an extra 'parent bone' (not to be confused with their Blender parent -- I know, the name is unfortunate) that is simply used by FromSoft as a way to group Dummies together by purpose. The name of this parent bone is just a string in the FLVER Dummy Properties Panel (usually 'sfx_dmy', 'Model_dmy') and is generally a root bone that isn't ever used by animations. - The most important property of each dummy is its reference ID. This is so important that it is stored directly in the Dummy's name, which follows a tightly controlled format: {model_name} Dummy<{index} [{reference_id}]. The model name is only used to make sure the Dummy has a unique name across Blender, and the index is only used to make sure that Dummies are listed in the same order as the FLVER file, but the reference ID is real data that determines how every other game file (TAE, EMEVD, etc.) refers to this Dummy. Multiple Dummies can have the same reference ID (e.g. 200, which is used at all the points where death visual effects are spawned)."

Each FLVER Material -- and some Submesh properties -- are represented by a Blender Material. Each material has a number of properties that can be set in the FLVER Material Properties Panel in the Material Properties window:

Each FLVER Mesh in Blender is a combination of all 'submeshes' that appeared in the FLVER file, which are already optimized for rendering but often painful to edit separately due to being disconnected along certain edges (e.g. where a grass texture changes to a rock texture on the ground). If Merge Submesh Vertices is enabled when the FLVER is imported, these submeshes will be merged into a single mesh by Soulstruct using a complicated algorithm that takes materials and vertex information into account. Otherwise, the submeshes will remain disconnected. Either way, each face in the Blender Mesh is assigned to a Blender Material that reflects a combination of its FLVER material and a handful of FLVER submesh properties that Soulstruct stores on each Blender Material: - Is Bind Pose: enabled for rigged/animated FLVER meshes and disabled for static FLVERs (generally just Map Pieces). This tells the game how to interpret vertex bone indices and weights. (Note that some Object FLVERs contain both static and animated submeshes.) - Default Bone Index: this seems to be rather useless and is often zero. - Face Set Count: number of face sets in the FLVER submesh, typically used for different levels of detail. Soulstruct cannot yet generate LODs, but has the option to copy the max-detail Mesh to this many face sets when the FLVER is exported (on