soulstruct 2.3.2__py3-none-any.whl

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/base/ai/__init__.py

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

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/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

soulstruct/base/ai/lua_scripts.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+__all__ = ["LuaScriptBase", "GoalType", "LuaGoalScript", "LuaUnknownScript"]
+
+import abc
+import copy
+import enum
+import logging
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from soulstruct.utilities.binary import *
+
+from .lua import LuaError, LuaCompileError, LuaDecompileError, compile_lua, decompile_lua
+
+_LOGGER = logging.getLogger(__name__)
+
+_SNAKE_CASE_RE = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+class GoalType(enum.Enum):
+    Battle = "battle"
+    Logic = "logic"
+    Unknown = "unknown"
+
+    @classmethod
+    def from_interrupt_info(cls, has_battle_interrupt: bool, has_logic_interrupt: bool, logic_interrupt_name: str):
+        if has_battle_interrupt and not has_logic_interrupt and not logic_interrupt_name:
+            return cls.Battle
+        elif not has_battle_interrupt and has_logic_interrupt and logic_interrupt_name:
+            return cls.Logic
+        elif not has_battle_interrupt and not has_logic_interrupt and not logic_interrupt_name:
+            return cls.Unknown
+        raise LuaError(
+            f"Could not determine goal type (battle={has_battle_interrupt}, logic={has_logic_interrupt}, "
+            f"logic_name={repr(logic_interrupt_name)})."
+        )
+
+
+@dataclass(slots=True)
+class LuaScriptBase(abc.ABC):
+
+    bytecode: bytes = b""
+    script: str = ""
+
+    def compile(self, output_path=None, x64=True):
+        """Generate `bytecode` from current `script`."""
+        if not self.script:
+            raise LuaCompileError(f"No Lua script to compile for {self.script_name}.")
+        self.bytecode = compile_lua(self.script, script_name=self.script_name, output_path=output_path, x64=x64)
+
+    def decompile(self, output_path=None):
+        """Generate `script` from current `bytecode`."""
+        if not self.bytecode:
+            raise LuaDecompileError(f"No compiled Lua to decompile for {self.script_name}.")
+        self.script = decompile_lua(self.bytecode, script_name=self.script_name, output_path=output_path)
+
+    def write_bytecode(self, lua_path):
+        if not self.bytecode:
+            raise LuaError(f"No compiled Lua bytecode to write for {self.script_name}.")
+        lua_path = Path(lua_path)
+        lua_path.parent.mkdir(parents=True, exist_ok=True)
+        with lua_path.open("wb") as f:
+            f.write(self.bytecode)
+
+    def write_script(self, lua_path):
+        if not self.script:
+            raise LuaError(f"No decompiled Lua script to write for {self.script_name}.")
+        lua_path = Path(lua_path)
+        lua_path.parent.mkdir(parents=True, exist_ok=True)
+        with lua_path.open("w", encoding="shift_jis_2004") as f:
+            f.write(self.script)
+
+    def load_script(self, lua_path: Path | str):
+        lua_path = Path(lua_path)
+        with lua_path.open("r", encoding="shift_jis_2004") as f:
+            self.script = f.read()
+
+    def copy(self):
+        return copy.deepcopy(self)
+
+    @property
+    @abc.abstractmethod
+    def script_name(self) -> str:
+        raise NotImplementedError
+
+
+class LuaGoal32(BinaryStruct):
+    goal_id: int
+    name_offset: uint
+    logic_interrupt_name_offset: uint
+    has_battle_interrupt: bool
+    has_logic_interrupt: bool
+    _pad1: bytes = binary_pad(2, init=False)
+
+
+class LuaGoal64(BinaryStruct):
+    goal_id: int
+    has_battle_interrupt: bool
+    has_logic_interrupt: bool
+    _pad1: bytes = binary_pad(2, init=False)
+    name_offset: long
+    logic_interrupt_name_offset: long
+
+
+@dataclass(slots=True)
+class LuaGoalScript(LuaScriptBase):
+    """Goals can have type 'battle', 'logic', or 'neither'.
+
+    All 'battle' goals have `has_battle_interrupt=True`, `has_logic_interrupt=False`, and `logic_interrupt_name=""`.
+    Their names usually end in 'Battle' (no underscore), but this is not necessary (e.g. common battle functions).
+
+    All 'logic' goals have `has_battle_interrupt=False`, `has_logic_interrupt=True`, and
+    `logic_interrupt_name={goal_name_prefix}_Interupt` [sic]. The goal name always ends in '_Logic'.
+
+    All 'neither' goals have `has_battle_interrupt=False`, `has_logic_interrupt=False`, and `logic_interrupt_name=""`.
+    These goals are typically referenced in other files (e.g. 'CrystalLizard330000Runaway'). They can have any name.
+    """
+
+    goal_id: int = -1
+    goal_name: str = ""
+    goal_type: GoalType = GoalType.Unknown
+    script_name: str = ""
+
+    def __post_init__(self):
+        if not self.script_name:
+            self.script_name = self.get_auto_script_name()
+
+    @classmethod
+    def from_luainfo_reader(cls, reader: BinaryReader, long_varints: bool, encoding: str) -> LuaGoalScript:
+        goal_struct = LuaGoal64.from_bytes(reader) if long_varints else LuaGoal32.from_bytes(reader)
+        name = reader.unpack_string(offset=goal_struct.name_offset, encoding=encoding)
+        if goal_struct.logic_interrupt_name_offset > 0:
+            logic_interrupt_name = reader.unpack_string(
+                offset=goal_struct.logic_interrupt_name_offset, encoding=encoding
+            )
+        else:
+            logic_interrupt_name = ""
+
+        goal_type = GoalType.from_interrupt_info(
+            goal_struct.has_battle_interrupt, goal_struct.has_logic_interrupt, logic_interrupt_name
+        )
+
+        return LuaGoalScript(
+            goal_id=goal_struct.goal_id,
+            goal_name=name,
+            goal_type=goal_type,
+        )
+
+    def to_luainfo_writer(self, writer: BinaryWriter, long_varints: bool):
+
+        goal_kwargs = {
+            "has_battle_interrupt": self.goal_type == GoalType.Battle,
+            "has_logic_interrupt": self.goal_type == GoalType.Logic,
+        }
+
+        (LuaGoal64 if long_varints else LuaGoal32).object_to_writer(self, writer, **goal_kwargs)
+
+    def pack_logic_interrupt_name(self, writer: BinaryWriter, encoding: str):
+        if self.goal_type == GoalType.Logic:
+            if not self.goal_name.endswith("_Logic"):
+                raise LuaError(f"Lua logic goal name must end in '_Logic'. Invalid: {repr(self.goal_name)}")
+            logic_interrupt_name = self.goal_name[:-6] + "_Interupt"
+            writer.fill_with_position("logic_interrupt_name", obj=self)
+            writer.pack_z_string(logic_interrupt_name, encoding=encoding)
+        else:
+            writer.fill("logic_interrupt_name", 0, obj=self)
+
+    def validate_goal_name(self):
+        if self.goal_type == GoalType.Logic and not self.goal_name.endswith("_Logic"):
+            raise LuaError(f"Logic goal name must end in '_Logic'. Invalid: {repr(self.goal_name)}")
+        elif self.goal_type == "battle" and not self.goal_name.endswith("Battle"):
+            _LOGGER.warning(f"Battle goal name {repr(self.goal_name)} does not end in 'Battle', which is unusual.")
+
+    def get_auto_script_name(self):
+        if self.goal_type == GoalType.Battle:
+            return f"{self.goal_id:06d}_battle.lua"
+        elif self.goal_type == GoalType.Logic:
+            return f"{self.goal_id:06d}_logic.lua"
+        elif self.goal_type == GoalType.Unknown:
+            # Shouldn't happen anymore.
+            snake_case_name = _SNAKE_CASE_RE.sub("_", self.goal_name).lower()
+            return f"{snake_case_name}.lua"
+        raise ValueError(f"Invalid `LuaGoal.type`: {self.goal_type}")
+
+    def get_interrupt_details(self):
+        if self.goal_type == GoalType.Battle:
+            return {"has_battle_interrupt": True, "has_logic_interrupt": False, "logic_interrupt_name": ""}
+        elif self.goal_type == GoalType.Logic:
+            if self.goal_name.endswith("_Logic"):
+                name = self.goal_name[:-6] + "_Interupt"
+            else:
+                raise LuaError(f"Logic goal name must end in '_Logic'. Invalid: {repr(self.goal_name)}")
+            return {"has_battle_interrupt": False, "has_logic_interrupt": True, "logic_interrupt_name": name}
+        elif self.goal_type == GoalType.Unknown:
+            return {"has_battle_interrupt": False, "has_logic_interrupt": False, "logic_interrupt_name": ""}
+
+    def __repr__(self):
+        return f"LuaGoal({self.goal_id:06d}, {repr(self.goal_name)}, {repr(self.goal_type)})"
+
+
+@dataclass(slots=True)
+class LuaUnknownScript(LuaScriptBase):
+
+    name: str = ""
+
+    @property
+    def script_name(self):
+        return f"{self.name}.lua"
+
+    def __repr__(self):
+        return f"LuaUnknownScript(name={repr(self.name)})"