soulstruct 2.3.2__tar.gz

soulstruct-2.3.2/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: soulstruct
+Version: 2.3.2
+Summary: Inspect and modify files in FromSoftware games.
+Author-email: "Scott Mooney (Grimrukh)" <grimrukh@gmail.com>
+License-Expression: GPL-3.0-or-later
+Project-URL: homepage, https://github.com/Grimrukh/soulstruct
+Project-URL: repository, https://github.com/Grimrukh/soulstruct
+Project-URL: Issues, https://github.com/Grimrukh/soulstruct/issues
+Keywords: modding,FromSoftware,Dark Souls,Bloodborne,Elden Ring,Sekiro,Demon's Souls
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: constrata>=1.3.1
+Requires-Dist: numpy
+Requires-Dist: rich>=13
+Requires-Dist: typer
+Requires-Dist: zstandard
+Provides-Extra: runtime
+Requires-Dist: psutil; extra == "runtime"
+Provides-Extra: graphs
+Requires-Dist: matplotlib; extra == "graphs"
+Provides-Extra: sound
+Requires-Dist: pydub; extra == "sound"
+
+# soulstruct
+Python tools for inspecting and modding From Software games, including an "all-in-one" graphical interface.
+
+**YouTube channel with tutorials: https://youtube.com/grimrukh**
+
+**Like my stuff? Consider supporting me on Patreon <3 https://patreon.com/Grimrukh**
+
+Game abbreviations used below and in package:
+- **DS1PTDE**: Dark Souls: Prepare to Die Edition
+- **DS1R**: Dark Souls Remastered
+- **DS2**: Dark Souls II (either version)
+- **BB**: Bloodborne
+- **DS3**: Dark Souls III
+- **SEK**: Sekiro: Shadows Die Twice
+- **ER**: Elden Ring
+
+Features
+--------
+
+- Unified graphical application for modifying maps, events, parameters, text, AI, and talk scripts in *Dark Souls* 
+  (both versions) and *Bloodborne*. Game data is imported as a **project**, edited in the window (or in Python if you 
+  prefer), and exported back to game-ready files whenever you want. Keep track of map entities, quickly navigate between 
+  data types, and view custom syntax highlighting for event scripts and AI scripts.
+  - Supported games: DS1PTDE, DS1R, BB
+
+- Event scripts (**EMEVD**) and EzState state machines (**ESD**) can be translated to and from valid Python-based 
+languages with high-level programming features.
+    - Supported games: DS1PTDE, DS1R, DS2 (ESD only), BB, DS3
+
+- Map data (**MSB**), game parameters (**GameParam**), lighting parameters (**DrawParam**), text data (**FMG**) can be 
+loaded into Python structures, edited, and repacked.
+    - Supported games: DS1PTDE, DS1R, BB (map, game parameters, and text only), DS3 (map and text only)
+
+- AI scripts in can be decompiled, edited, and recompiled.
+    - Supported games: DS1PTDE (no decompiling), DS1R
+
+- Unpack/repack **BND** archives and automatically manage **DCX** compression.
+    - Supported games: all
+
+- Includes some of my ongoing documentation for vanilla game IDs in *Dark Souls* and *Bloodborne*.

soulstruct-2.3.2/README.md

@@ -0,0 +1,40 @@
+# soulstruct
+Python tools for inspecting and modding From Software games, including an "all-in-one" graphical interface.
+
+**YouTube channel with tutorials: https://youtube.com/grimrukh**
+
+**Like my stuff? Consider supporting me on Patreon <3 https://patreon.com/Grimrukh**
+
+Game abbreviations used below and in package:
+- **DS1PTDE**: Dark Souls: Prepare to Die Edition
+- **DS1R**: Dark Souls Remastered
+- **DS2**: Dark Souls II (either version)
+- **BB**: Bloodborne
+- **DS3**: Dark Souls III
+- **SEK**: Sekiro: Shadows Die Twice
+- **ER**: Elden Ring
+
+Features
+--------
+
+- Unified graphical application for modifying maps, events, parameters, text, AI, and talk scripts in *Dark Souls* 
+  (both versions) and *Bloodborne*. Game data is imported as a **project**, edited in the window (or in Python if you 
+  prefer), and exported back to game-ready files whenever you want. Keep track of map entities, quickly navigate between 
+  data types, and view custom syntax highlighting for event scripts and AI scripts.
+  - Supported games: DS1PTDE, DS1R, BB
+
+- Event scripts (**EMEVD**) and EzState state machines (**ESD**) can be translated to and from valid Python-based 
+languages with high-level programming features.
+    - Supported games: DS1PTDE, DS1R, DS2 (ESD only), BB, DS3
+
+- Map data (**MSB**), game parameters (**GameParam**), lighting parameters (**DrawParam**), text data (**FMG**) can be 
+loaded into Python structures, edited, and repacked.
+    - Supported games: DS1PTDE, DS1R, BB (map, game parameters, and text only), DS3 (map and text only)
+
+- AI scripts in can be decompiled, edited, and recompiled.
+    - Supported games: DS1PTDE (no decompiling), DS1R
+
+- Unpack/repack **BND** archives and automatically manage **DCX** compression.
+    - Supported games: all
+
+- Includes some of my ongoing documentation for vanilla game IDs in *Dark Souls* and *Bloodborne*.

soulstruct-2.3.2/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "soulstruct"
+description = "Inspect and modify files in FromSoftware games."
+readme = "README.md"
+version = "2.3.2"
+license = "GPL-3.0-or-later"
+requires-python = ">=3.11"  # maximum allowed for Blender 4.5-5.0 support
+keywords = ["modding", "FromSoftware", "Dark Souls", "Bloodborne", "Elden Ring", "Sekiro", "Demon's Souls"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+]
+authors = [
+    { name = "Scott Mooney (Grimrukh)", email = "grimrukh@gmail.com" }
+]
+
+dependencies = [
+    "constrata>=1.3.1",     # required for binary read/write (my package)
+    "numpy",                # required for math classes/operations
+    "rich>=13",             # required for nice printing/logging
+    "typer",                # required for CLI
+    "zstandard",            # required for ZSTD compression (Elden Ring regulation DCX)
+]
+
+[tool.setuptools.package-data]
+"*" = ["*.dll", "*.exe"]  # include embedded DLLs and EXEs in all subpackages
+
+[project.optional-dependencies]
+runtime       = ["psutil"]
+graphs        = ["matplotlib"]
+sound         = ["pydub"]
+
+[project.scripts]
+soulstruct = "soulstruct.__main__:app"
+
+[project.urls]
+homepage      = "https://github.com/Grimrukh/soulstruct"
+repository    = "https://github.com/Grimrukh/soulstruct"
+"Issues"      = "https://github.com/Grimrukh/soulstruct/issues"

soulstruct-2.3.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

soulstruct-2.3.2/src/soulstruct/__main__.py

@@ -0,0 +1,175 @@
+"""
+Soulstruct command-line interface (and `python -m soulstruct` main script).
+
+Runs as either
+
+    python -m soulstruct ...
+
+or the console script installed from pyproject.toml:
+
+    soulstruct ...
+
+Global logging options come first, followed by sub-commands.
+"""
+from __future__ import annotations
+
+__all__ = [
+    "app",
+]
+
+import logging
+from pathlib import Path
+
+import typer
+
+from soulstruct.logging_utils import setup
+from soulstruct.utilities.files import create_bak
+
+LOG_LEVELS = {"debug", "info", "warning", "error", "fatal", "critical"}
+_LOGGER = logging.getLogger(__name__)
+
+
+def _parse_level(value: str) -> int:
+    """Convert a level name (info) or int string (20) ➜ logging level."""
+    if value.isdigit():
+        return int(value)
+    if value.lower() in LOG_LEVELS:
+        return getattr(logging, value.upper())
+    raise typer.BadParameter(f"Log level must be int or one of {LOG_LEVELS}")
+
+
+# Typer application.
+app = typer.Typer(
+    add_completion=False,
+    help="Launch Soulstruct utilities (packing/unpacking, conversion, etc.).",
+)
+
+# Global options executed before any sub-command.
+@app.callback()
+def main(
+    console_log_level: str = typer.Option(
+        "INFO", "--console-log-level", "-cl", help="Console log level (DEBUG/INFO/…)."
+    ),
+    file_log_level: str = typer.Option(
+        "DEBUG", "--file-log-level", "-fl", help="Log-file level (DEBUG/INFO/…)."
+    ),
+    file_log_path: Path = typer.Option(
+        None,
+        "--file-log-path",
+        "-fp",
+        help="Path to log file (default: `soulstruct.log` in current directory).",
+    ),
+):
+    """Global logging controls (executed before sub-commands)."""
+    setup(
+        console_level=console_log_level,
+        file_level=file_log_level,
+        log_path=file_log_path,
+        rich_tracebacks=True,
+        clear_old_handlers=True,
+    )
+
+
+# region Commands
+
+@app.command()
+def undcx(path: Path):
+    """Remove DCX compression (writes *.undcx or suffix-free file)."""
+    from soulstruct.dcx import decompress
+
+    uncompressed, _dcx_type = decompress(path)
+    out = path.with_suffix("") if path.suffix == ".dcx" else path.with_suffix(".undcx")
+    if out.exists():
+        create_bak(out)
+    out.write_bytes(uncompressed)
+    _LOGGER.info("Wrote %s", out)
+
+
+@app.command()
+def binderpack(source_dir: Path):
+    """Re-pack a BND/BXF from directory *SOURCE_DIR*."""
+    from soulstruct.containers import Binder
+
+    Binder.from_unpacked_path(source_dir).write()
+
+
+@app.command()
+def binderunpack(binder_file: Path):
+    """Unpack a BND/BXF file."""
+    from soulstruct.containers import Binder
+
+    Binder.from_path(binder_file).write_unpacked_directory()
+
+
+@app.command()
+def tpfpack(source_dir: Path):
+    """Re-pack a TPF from directory *SOURCE_DIR*."""
+    from soulstruct.containers.tpf import TPF
+
+    TPF.from_unpacked_path(source_dir).write()
+
+
+@app.command()
+def tpfunpack(tpf_file: Path):
+    """Unpack a TPF file."""
+    from soulstruct.containers.tpf import TPF
+
+    TPF.from_path(tpf_file).write_unpacked_directory()
+
+
+@app.command()
+def msbtojson(msb_path: Path):
+    """Convert an MSB file to JSON (DS1R only)."""
+    from soulstruct.darksouls1r.maps import MSB
+
+    msb = MSB.from_path(msb_path)
+    out = msb.path.with_suffix(f"{msb.path.suffix}.json")
+    msb.write_json(out)
+    _LOGGER.info("Wrote %s", out)
+
+
+@app.command()
+def jsontomsb(json_path: Path):
+    """Convert a JSON file back to MSB (DS1R only)."""
+    from soulstruct.darksouls1r.maps import MSB
+
+    msb = MSB.from_json(json_path)
+    out = msb.path.with_name(f"{msb.path_minimal_stem}.msb")
+    msb.write(out)
+    _LOGGER.info("Wrote %s", out)
+
+
+@app.command()
+def restorebak(
+    target: Path,
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompts."),
+):
+    """Restore *.bak files, overwriting originals."""
+    from soulstruct.utilities.files import restore_bak
+
+    def _confirm(msg: str) -> bool:
+        return yes or typer.confirm(msg)
+
+    if target.is_file():
+        repl = target.with_name(target.name.removesuffix(".bak"))
+        if repl.exists() and not _confirm(f"Overwrite {repl} with {target}?"):
+            raise typer.Abort()
+    elif target.is_dir():
+        if not _confirm(f"Restore all .bak files in {target}?"):
+            raise typer.Abort()
+    else:
+        _LOGGER.warning("No such file or directory: %s", target)
+        raise typer.Exit(1)
+
+    count = restore_bak(target, delete_baks=False)
+    _LOGGER.info("Restored %s bak files (bak files kept).", count)
+
+# endregion
+
+
+if __name__ == "__main__":
+    try:
+        app()
+    except Exception as ex:
+        _LOGGER.exception("Unhandled exception: %s", ex)
+        input("Press any key to exit.")

soulstruct-2.3.2/src/soulstruct/base/ai/__init__.py

@@ -0,0 +1,2 @@
+from .ai_directory import AIScriptDirectory
+from .luabnd import LuaBND

soulstruct-2.3.2/src/soulstruct/base/ai/ai_directory.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+__all__ = ["AIScriptDirectory"]
+
+import abc
+import logging
+import typing as tp
+from dataclasses import field
+from pathlib import Path
+
+from soulstruct.base.game_file_directory import GameFileMapDirectory
+from .luabnd import LuaBND
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class AIScriptDirectory(GameFileMapDirectory[LuaBND], abc.ABC):
+    """Unpack LuaBND scripts in a directory (usually `script`) into one single modifiable structure.
+
+    Note that the vanilla game uses pre-compiled Lua bytecode for a minor efficiency upgrade, but uncompiled Lua
+    scripts work just as well. Use the `.decompile_all()` method to generate them from any compiled scripts
+    (currently does not work for PTDE or Bloodborne).
+    TODO: Has Katalash upgraded this decompiler to support Bloodborne?
+
+    The same script will work in both PTDE and DSR, but decompiling is only offered (with Katalash's
+    'DSLuaDecompiler' tool) for DSR. PTDE files have the variable names stripped anyway, which makes them much
+    harder to edit even when decompiled. If you want to customize PTDE scripts, I recommend doing all the work in
+    DSR and then just copying the scripts over.
+
+    `aiCommon.luabnd` ('Common') contains scripts that are loaded in all maps, which includes internal scripts
+    with global functions that are accessed in every script. If you want to decompile these internal scripts, you
+    must call `AIScriptDirectory.Common.decompile(battle_or_logic_only=False)`, and similar to recompile them
+    (for testing) or save the decompiled scripts into the LuaBND.
+
+    `eventCommon.luabnd` contains scripts that are solely internal. This BND is unpacked in `.event_common_bnd`
+    for manual inspection and modification, if you really want, but this shouldn't be necessary. It is written
+    automatically by `.save()`.
+
+    Note that you only need to reload the map (e.g. by saving and quitting, or getting sufficiently far away from
+    the map) to see changes in these files while playing the game. You do NOT need to fully restart the game, unlike
+    with text and parameter/lighting changes, *UNLESS* you need to reload a script in Common.
+    """
+    FILE_NAME_PATTERN: tp.ClassVar[str] = r".*\.luabnd"
+    FILE_CLASS: tp.ClassVar[type[LuaBND]] = LuaBND
+    FILE_EXTENSION = ".luabnd"
+    MAP_STEM_ATTRIBUTE = "ai_file_stem"
+
+    files: dict[str, LuaBND] = field(default_factory=dict)
+
+    @classmethod
+    def from_unpacked_luabnds(cls, directory_path: Path | str):
+        """Open a collection of unpacked `LuaBND` binders instead of the binders themselves."""
+
+        directory_path = Path(directory_path)
+        if not directory_path.is_dir():
+            raise NotADirectoryError(f"Missing directory: {directory_path}")
+        all_map_stems = [getattr(game_map, cls.MAP_STEM_ATTRIBUTE) for game_map in cls.ALL_MAPS]
+        all_map_stems = [stem for stem in all_map_stems if stem is not None]
+        files = {}
+        for file_path in directory_path.glob("*"):
+            if file_path.is_dir() and file_path.stem in all_map_stems:
+                # Try to load `LuaBND` from unpacked binder.
+                files[file_path.stem] = cls.FILE_CLASS.from_unpacked_path(file_path)
+                all_map_stems.remove(file_path.stem)
+                continue
+
+        if all_map_stems:
+            _LOGGER.warning(f"Could not find some files in `{cls.__name__}` directory: {', '.join(all_map_stems)}")
+
+        return cls(directory=directory_path, files=files)
+
+    def write_unpacked_luabnds(self, directory_path: Path | str = None):
+        if directory_path is None:
+            if self.directory is None:
+                raise ValueError("Cannot autodetect directory name (`directory` not set).")
+            directory_path = self.directory
+        directory_path = Path(directory_path)
+        all_map_stems = [getattr(game_map, self.MAP_STEM_ATTRIBUTE) for game_map in self.ALL_MAPS]
+        directory_path.mkdir(parents=True, exist_ok=True)
+        for file_stem, luabnd in self.files.items():
+            if file_stem in all_map_stems:
+                all_map_stems.remove(file_stem)
+            else:
+                _LOGGER.warning(f"Writing unknown LuaBND file found in `{self.__class__.__name__}`: {file_stem}")
+            luabnd.write_unpacked_directory(directory_path / f"{file_stem}")
+        if all_map_stems:
+            _LOGGER.warning(
+                f"Could not find some file keys while writing `{self.__class__.__name__}` directory: "
+                f"{', '.join(all_map_stems)}"
+            )
+        _LOGGER.info(
+            f"`{self.__class__.__name__}` unpacked LuaBNDs written to `{directory_path}` successfully "
+            f"({len(self.files)} folders)."
+        )
+
+    def compile_all(self, output_directory=None, include_unknown_scripts=False):
+        for luabnd_stem, luabnd in self.files.items():
+            _LOGGER.info(f"Compiling Lua scripts in {luabnd_stem}...")
+            luabnd.compile_all(output_directory, include_unknown_scripts)
+
+    def decompile_all(self, output_directory=None, include_unknown_scripts=False):
+        for luabnd_stem, luabnd in self.files.items():
+            _LOGGER.info(f"Decompiling Lua scripts in {luabnd_stem}...")
+            luabnd.decompile_all(output_directory, include_unknown_scripts)

soulstruct-2.3.2/src/soulstruct/base/ai/lua/__init__.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+__all__ = [
+    "LuaError",
+    "LuaCompileError",
+    "LuaDecompileError",
+    "compile_lua",
+    "decompile_lua",
+]
+
+import logging
+import os
+import subprocess
+from contextlib import contextmanager
+from pathlib import Path
+
+from soulstruct.exceptions import SoulstructError
+from soulstruct.utilities.files import SOULSTRUCT_PATH
+from soulstruct.utilities.misc import get_startupinfo
+
+_LOGGER = logging.getLogger(__name__)
+
+COMPILER_x64 = str(SOULSTRUCT_PATH("base/ai/lua/x64/LuaC.exe"))
+COMPILER_x86 = str(SOULSTRUCT_PATH("base/ai/lua/x86/luac50.exe"))
+DECOMPILER_x64 = str(SOULSTRUCT_PATH("base/ai/lua/x64/DSLuaDecompiler.exe"))
+# No x86 decompiler.
+
+
+class LuaError(SoulstructError):
+    pass
+
+
+class LuaCompileError(LuaError):
+    pass
+
+
+class LuaDecompileError(LuaError):
+    pass
+
+
+@contextmanager
+def _temp_lua_path(content, as_bytes=False, encoding=None, set_cwd=False):
+    temp = SOULSTRUCT_PATH("base/ai/lua/temp")
+    if set_cwd:
+        previous_cwd = os.getcwd()
+        os.chdir(str(temp.parent))
+    else:
+        previous_cwd = None
+    with temp.open(mode="wb" if as_bytes else "w", encoding=encoding) as f:
+        f.write(content)
+    yield temp
+    try:
+        os.remove(str(SOULSTRUCT_PATH("base/ai/lua/temp")))
+    except FileNotFoundError:
+        pass
+    if previous_cwd:
+        os.chdir(previous_cwd)
+
+
+def compile_lua(script: str, script_name="<unknown script>", output_path=None, x64=True):
+    with _temp_lua_path(script, as_bytes=False, set_cwd=True, encoding="shift_jis_2004") as temp:
+        compiler_path = COMPILER_x64 if x64 else COMPILER_x86
+        result = subprocess.run(
+            [compiler_path, "-o", "temp.lua", temp],
+            text=True,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            startupinfo=get_startupinfo(),
+        )
+        if result.stdout.strip():
+            _LOGGER.warning(f"Lua Compiler Warning for script {script_name}: {result.stdout.strip()}")
+        if result.returncode != 0:
+            raise LuaCompileError(f"Script {script_name}: {result.stderr.strip()}")
+        with Path("temp.lua").open("rb") as f:
+            bytecode = f.read()
+        os.remove("temp.lua")
+        if output_path:
+            with Path(output_path).open("wb") as o:
+                o.write(f.read())
+        return bytecode
+
+
+def decompile_lua(bytecode: bytes, script_name="<unknown script>", output_path=None):
+    if output_path:
+        output_path = Path(output_path).resolve()  # resolve before changing to temp working dir
+    with _temp_lua_path(bytecode, as_bytes=True, set_cwd=True) as temp:
+        result = subprocess.run(
+            [DECOMPILER_x64, temp],
+            text=True,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            startupinfo=get_startupinfo(),
+        )
+        if result.stdout.strip():
+            _LOGGER.warning(f"Lua Decompiler Warning for script {script_name}: {result.stdout.strip()}")
+        if result.returncode != 0:
+            raise LuaDecompileError(f"Script {script_name}: {result.stderr.strip()}")
+        with Path("temp.dec.lua").open("r", encoding="shift_jis_2004") as f:
+            script_string = f.read()
+        os.remove("temp.dec.lua")
+        if output_path:
+            output_path = Path(output_path)
+            output_path.parent.mkdir(exist_ok=True, parents=True)
+            with Path(output_path).open("w", encoding="shift_jis_2004") as o:
+                o.write(script_string)
+                _LOGGER.info(f"Decompiled Lua file written: {str(output_path)}")
+        return script_string