Soulstruct is a many-in-one tool for modding game data and scripts in Dark Souls (either game version). It's a graphical interface built around the Python package of the same name.

Recent updates:

• 1.1.1: Fixed import bug.
• 1.1.0: Custom script support added, and Bloodborne project bug fixed.
• 1.0.0: Big internal overhaul, Bloodborne support, and bug fixes.
• 0.10.3: Config export fixed (from GUI File menu).
• 0.10.2: Errors logged properly, some field name updates.
• 0.10.1: Runtime hook fixed.
• 0.10.0: Faster runtime hook, pop-out draw group editor, custom enum values, and various linking/bug fixes.
  

NOTE: Your antivirus software may flag the Soulstruct executable as malicious, which is likely due to a combination of the game-hook code and the software used to convert Python code to an executable file (PyInstaller). If you're concerned about it, you can always use the Python module directly from GitHub!

See the GitHub release page for a more comprehensive version history.

Simply run the executable, point it to an empty or existing project directory, and (if it's a new project) point it to the Dark Souls executable for either game version. The mod will ask if you want to import game files. Say yes (and wait a bit), and the window will open, ready for modding. Use the export options at the top or in the File menu to export individual data types or export the entire project. (Note that Params contains a lot of data and take a few seconds to export.) You can also re-import particular game types, re-import everything, and import or export from arbitrary game folders if that's relevant to your setup.

You can use the File > Set as Default Project option to set the current project as the default (or edit the config.py file that will appear next to the executable).

If anything goes wrong, check the contents of the soulstruct.log file that should appear next to the executable before you submit a bug. It will contain the error log from the last time the executable was run.


NOTE: In these early days of Soulstruct, I may occasionally make changes to the internal structure of project files (the .d1s files that store your modded game data). This is necessary as we learn more about what certain unknown variables do. When such a change happens, you may need to export the changed file type (e.g. Maps) from the old version of Soulstruct (to binary game files), then import those binary game files into the new version. You can use the "Export to..." and "Import from..." options in the "File" menu to do this with arbitrary directories rather than exporting to the actual game directory. (If you don't care about that data type, you can also just delete the old .d1s file and Soulstruct will prompt you to import it fresh from the game.)

As of version 0.5.4, Soulstruct will try to guess when such an internal change is the cause of an error (which will usually occur when you try to export an old project in a new version of Soulstruct). I'll try to combine these changes together as much as possible, and flag releases below where you may need to do this export/import trick.

Features:

• Unified graphical application for modifying maps, events, parameters, text, AI, and scripts in Dark Souls (either version). Game data is imported as a project, edited in the GUI, saved locally, and exported back to binary game-ready files whenever you want.
• Map data (MSB), game parameters (GameParam), lighting parameters (DrawParam), and text data (FMG) are imported into user-friendly tables for editing.
• Event scripts (EMEVD) and EzState state machines (ESD) can be translated to and from valid Python-based languages.
• AI scripts in Dark Souls can be decompiled, edited, and recompiled.
• Keep track of map entities, quickly navigate between data types with right-click hyperlinks, and view custom syntax highlighting for event scripts, AI scripts, and talk scripts.
• Hover over parameter field names and buttons to see what they do (note that some are still undocumented).
• Includes tools for unpacking/repacking BND archives, and automatically manages DCX compression.
• Includes my ongoing documentation for game IDs in Dark Souls.
  

Note: modified AI data has not yet been thoroughly tested in-game.

Documentation is currently sparse, but I have a tutorial series starting up very soon on my YouTube channel. I'll update with a link here when that happens!

You can post any bugs or suggested features here. (I know that undo/redo commands and back/forward view changes are high on the priority list.)

Thanks to everyone in the Dark Souls modding community who helped reverse-engineer the game files or generally contribute to our understanding of how they work. In particular: wulf2k, HotPocketRemix, TKGP, katalash, Meowmaritus, and thefifthmatt. Soulstruct uses katalash's decompiler for AI scripts, which in turn uses TKGP's SoulsFormats .NET library.

If you find Soulstruct, my tutorials, or my mods valuable, please consider supporting me at Patreon!

~Grimrukh