tfbscript 0.1.0__py3-none-any.whl

tfbscript/__init__.py

@@ -0,0 +1,21 @@
+"""Parser and decompiler for TFB script (.ai) files."""
+
+from tfbscript.binary import BinaryReader
+from tfbscript.payload import PayloadReader
+from tfbscript.reference import Reference
+from tfbscript.rhs import Rhs
+from tfbscript.script import ScriptFile
+from tfbscript.string_table import StringTable, StringTableEntry
+from tfbscript.editor import open_editor, editor_from_filepath
+
+__all__ = [
+    "BinaryReader",
+    "PayloadReader",
+    "Reference",
+    "Rhs",
+    "ScriptFile",
+    "StringTable",
+    "StringTableEntry",
+    "open_editor",
+    "editor_from_filepath"
+]

tfbscript/__main__.py

@@ -0,0 +1,52 @@
+"""CLI: decompile TFB script (.ai) files to pretty-printed pseudo-source.
+
+Usage:
+    python -m tfbscript example_scripts/Teleporter.ai
+    python -m tfbscript --no-color example_scripts/*.ai
+"""
+
+import argparse
+import sys
+
+from tfbscript.ansi import disable_colors, enable_colors
+from tfbscript.script import ScriptFile
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="tfbscript",
+        description="Decompile TFB script (.ai) files to pretty-printed pseudo-source.",
+    )
+    parser.add_argument("files", nargs="+", help="one or more .ai script files")
+    color_group = parser.add_mutually_exclusive_group()
+    color_group.add_argument(
+        "--no-color",
+        action="store_true",
+        help="disable ANSI syntax coloring (auto-disabled when piped or NO_COLOR is set)",
+    )
+    color_group.add_argument(
+        "--color",
+        action="store_true",
+        help="force ANSI syntax coloring even when piped",
+    )
+    args = parser.parse_args(argv)
+
+    if args.no_color:
+        disable_colors()
+    elif args.color:
+        enable_colors()
+
+    status = 0
+    for path in args.files:
+        if len(args.files) > 1:
+            print(f"===== {path} =====")
+        try:
+            ScriptFile.from_path(path).print_tree()
+        except (OSError, ValueError) as error:
+            print(f"{path}: {error}", file=sys.stderr)
+            status = 1
+    return status
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tfbscript/ansi.py

@@ -0,0 +1,203 @@
+"""Centralized ANSI syntax highlighting for TFBScript pretty-printing.
+
+Usage:
+    from tfbscript.ansi import keyword
+
+    print(keyword("var"))
+
+Coloring is on by default when stdout is a real terminal, and off when
+piped/redirected or when the NO_COLOR env var is set (https://no-color.org).
+Override explicitly with enable_colors() / disable_colors() / set_colors_enabled(),
+e.g. to add a --no-color CLI flag to a script.
+"""
+
+import os
+import sys
+from enum import Enum
+
+_RESET = "\033[0m"
+
+
+if sys.platform == "win32":
+
+    def _enable_windows_vt100() -> bool:
+        """Turn on ANSI (virtual terminal) processing for the Windows console."""
+        try:
+            import ctypes
+
+            STD_OUTPUT_HANDLE = -11
+            ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x0004
+
+            kernel32 = ctypes.windll.kernel32
+            handle = kernel32.GetStdHandle(STD_OUTPUT_HANDLE)
+
+            mode = ctypes.c_uint32()
+            if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+                return False
+
+            return bool(
+                kernel32.SetConsoleMode(
+                    handle,
+                    mode.value | ENABLE_VIRTUAL_TERMINAL_PROCESSING,
+                )
+            )
+        except Exception:  # noqa: BLE001
+            return False
+
+else:
+
+    def _enable_windows_vt100() -> bool:
+        """No-op on non-Windows platforms."""
+        return True
+
+
+def _detect_default() -> bool:
+    if os.environ.get("NO_COLOR") is not None:
+        return False
+    if os.environ.get("FORCE_COLOR") is not None:
+        return True
+    if not getattr(sys.stdout, "isatty", lambda: False)():
+        return False
+    if sys.platform == "win32":
+        return _enable_windows_vt100()
+    return True
+
+
+_enabled = _detect_default()
+
+
+def colors_enabled() -> bool:
+    return _enabled
+
+
+def set_colors_enabled(value: bool) -> None:
+    global _enabled
+    _enabled = value
+
+
+def enable_colors() -> None:
+    set_colors_enabled(True)
+
+
+def disable_colors() -> None:
+    set_colors_enabled(False)
+
+
+def _fg_rgb(r: int, g: int, b: int) -> str:
+    return f"\033[38;2;{r};{g};{b}m"
+
+
+def _fg(hex_color: str) -> str:
+    hex_color = hex_color.lstrip("#")
+    r, g, b = (int(hex_color[i : i + 2], 16) for i in (0, 2, 4))
+    return _fg_rgb(r, g, b)
+
+
+class Color(Enum):
+    """Syntax categories, colored after the One Dark Pro theme."""
+
+    # Punctuation
+    PARENTHESES = "#5C6370"  # muted gray
+
+    # Operators
+    OPERATOR = "#56B6C2"  # cyan
+    COMPARISON = "#56B6C2"  # cyan
+
+    # Language keywords
+    KEYWORD = "#C678DD"  # purple
+    FLOW_CONTROL = "#E06C75"  # red
+
+    # Literals
+    STRING = "#98C379"  # green
+    NUMBER = "#D19A66"  # orange
+    TYPE = "#E5C07B"  # yellow
+    BUILTIN = "#E5C07B"  # yellow
+
+    # Identifiers
+    VARIABLE = "#E06C75"  # red
+    VARIABLE_GLOBAL = "#61AFEF"  # blue
+    METHOD = "#61AFEF"  # blue
+
+    # Comments
+    COMMENT = "#5C6370"  # muted gray
+
+    INLINE_FUNC_OP = "#6458EC"
+
+
+def color_text(text: object, color: Color) -> str:
+    """Wrap text in `color`'s ANSI code; passes it through unchanged if coloring is off."""
+    if not _enabled:
+        return str(text)
+    return f"{_fg(color.value)}{text}{_RESET}"
+
+
+# Shorthand for each syntax category, e.g. keyword("if") instead of
+# color_text("if", Color.KEYWORD) -- use these when building source_line()
+# output for opcodes so call sites read like the syntax they represent.
+def parentheses(text: object) -> str:
+    return color_text(text, Color.PARENTHESES)
+
+
+def operator(text: object) -> str:
+    return color_text(text, Color.OPERATOR)
+
+
+def comparison(text: object) -> str:
+    return color_text(text, Color.COMPARISON)
+
+
+def keyword(text: object) -> str:
+    return color_text(text, Color.KEYWORD)
+
+
+def flow_control(text: object) -> str:
+    return color_text(text, Color.FLOW_CONTROL)
+
+
+def string(text: object) -> str:
+    return color_text(text, Color.STRING)
+
+
+def number(text: object) -> str:
+    return color_text(text, Color.NUMBER)
+
+
+def type_(text: object) -> str:
+    return color_text(text, Color.TYPE)
+
+
+def builtin(text: object) -> str:
+    return color_text(text, Color.BUILTIN)
+
+
+def variable(text: object) -> str:
+    return color_text(text, Color.VARIABLE)
+
+
+def variable_global(text: object) -> str:
+    return color_text(text, Color.VARIABLE_GLOBAL)
+
+
+def method(text: object) -> str:
+    return color_text(text, Color.METHOD)
+
+
+def comment(text: object) -> str:
+    return color_text(text, Color.COMMENT)
+
+
+def rgb_square(r: int, g: int, b: int) -> str:
+    """A small ■ swatch rendered in the given RGB, e.g. to preview a Color32 value."""
+    if not _enabled:
+        return ""
+    return f"{_fg_rgb(r, g, b)}■ {_RESET}"
+
+
+def quoted_string(text: str) -> str:
+    return string(f'"{text}"')
+
+
+def func_call(func_name: str, *args: str, add_semicolon=True) -> str:
+    """Format a function call with syntax highlighting."""
+    args_str = ", ".join(args)
+    return f"{method(func_name)}{parentheses('(')}{args_str}{parentheses(')')}{';' if add_semicolon else ''}"

tfbscript/arena.py

@@ -0,0 +1,119 @@
+"""The opcode-arena size stored in the .ai header.
+
+The 4-byte field after the magic string is not opaque: it is the size, in
+dwords, of the arena the loader allocates for the script's instruction objects.
+From ``TFBScript::read`` @ 004349e0 in Game.exe::
+
+    FUN_00432920(&count);                    // the header dword
+    DAT_0061f890 = FUN_00550170(count * 4);  // allocate the arena
+
+``read`` then carves ``1 + instructionCount`` dwords off the front for the
+instruction pointer array (plus its NULL terminator), and every instruction's
+``instantiate`` (vtable +0x30) bumps ``DAT_0061f890`` by that opcode's object
+size.  So::
+
+    header = 1 + instructionCount + sum(objectSize(opcode) / 4)
+
+Two accounting details, both recovered from the corpus rather than assumed:
+
+* instructions with ``flags.no_handler`` (bit 6) set are **still counted** --
+  the exporter reserves space for them even though the loader never constructs
+  them;
+* every 0xFF control-block marker costs 4 dwords, including the behavior
+  implementations past the first three.
+
+The per-opcode sizes below were solved as a linear system over the 577 shipped
+scripts (one equation per file, one unknown per opcode) and reproduce the
+stored header exactly for 575 of them.  The five that could be cross-checked
+against Game.exe's ``parse`` return values all agree: set value 0x18, control
+0x10, check message 0x1c, send message 0x1c, cut-scene 0x0c.
+"""
+
+from typing import TYPE_CHECKING, Iterator
+
+if TYPE_CHECKING:
+    from tfbscript.opcodes.base import Opcode
+    from tfbscript.script import ScriptFile
+
+# Cost of one 0xFF control-block marker (prescript/startup/shutdown/behavior).
+MARKER_DWORDS = 4
+
+# opcode table name -> object size in dwords.
+OPCODE_OBJECT_DWORDS: dict[str, int] = {
+    "comment:": 0,
+    "create variable": 0,
+    "if/else": 2,
+    "cut-scene": 3,
+    "dec value": 3,
+    "inc value": 3,
+    "play animation": 3,
+    "play sound": 3,
+    "remove": 3,
+    "reset": 3,
+    "run as player": 3,
+    "set behavior": 3,
+    "stop sound": 3,
+    "check reference": 4,
+    "control": 4,
+    "for each": 4,
+    "print": 4,
+    "set reference": 4,
+    "change membership": 5,
+    "check membership": 5,
+    "loop value": 5,
+    "turn to": 5,
+    "check value": 6,
+    "find subset": 6,
+    "find variable": 6,
+    "set value": 6,
+    "use camera": 6,
+    "check message": 7,
+    "move from": 7,
+    "move to": 7,
+    "send message": 7,
+    "spawn actor": 8,
+    "teleport to": 9,
+    "check fov": 12,
+    "displace": 12,
+    "slide value": 17,
+}
+
+
+def _walk(ops: "list[Opcode]") -> "Iterator[Opcode]":
+    for op in ops:
+        yield op
+        yield from _walk(op.children)
+
+
+def _marker_classes() -> tuple[type, ...]:
+    from tfbscript.opcodes.op_behavior_implementation import OpBehaviorImplementation
+    from tfbscript.opcodes.op_prescript import OpPrescript
+    from tfbscript.opcodes.op_shutdown import OpShutdown
+    from tfbscript.opcodes.op_startup import OpStartup
+
+    return (OpPrescript, OpStartup, OpShutdown, OpBehaviorImplementation)
+
+
+def arena_dwords(script: "ScriptFile") -> int | None:
+    """The header dword this script needs, or None if it can't be computed.
+
+    Returns None when the script contains an opcode with no known object size
+    (an unrecognised name, or the generic `Opcode` fallback) -- callers should
+    fall back to the value the file was read with rather than guess.
+    """
+    from tfbscript.opcodes.base import OPCODE_REGISTRY
+
+    name_of = {cls: name for name, cls in OPCODE_REGISTRY.items()}
+    markers = _marker_classes()
+
+    total = 1  # the pointer array's NULL terminator
+    for op in _walk(script.instructions):
+        total += 1  # this instruction's slot in the pointer array
+        if isinstance(op, markers):
+            total += MARKER_DWORDS
+            continue
+        size = OPCODE_OBJECT_DWORDS.get(name_of.get(type(op), ""))
+        if size is None:
+            return None
+        total += size
+    return total

tfbscript/binary.py

@@ -0,0 +1,84 @@
+"""A small binary reader over an in-memory buffer."""
+
+import struct
+from typing import BinaryIO
+
+
+class BinaryReader:
+    def __init__(self, data: bytes, little_endian: bool = True):
+        self.data = memoryview(data)
+        self.offset = 0
+        self.endian = "<" if little_endian else ">"
+
+    def tell(self) -> int:
+        return self.offset
+
+    def seek(self, offset: int) -> None:
+        self.offset = offset
+
+    def skip(self, count: int) -> None:
+        self.offset += count
+
+    def size_remaining(self) -> int:
+        return len(self.data) - self.offset
+
+    def eof(self) -> bool:
+        return self.offset >= len(self.data)
+
+    def read(self, fmt: str):
+        """Unpack a single value and advance the offset by its size."""
+        fmt = self.endian + fmt
+        value = struct.unpack_from(fmt, self.data, self.offset)[0]
+        self.offset += struct.calcsize(fmt)
+        return value
+
+    def read_bytes(self, count: int) -> bytes:
+        data = self.data[self.offset : self.offset + count].tobytes()
+        self.offset += count
+        return data
+
+    def read_string(self, length: int, encoding: str = "latin1") -> str:
+        return self.read_bytes(length).decode(encoding)
+
+    def read_u8(self) -> int:
+        return self.read("B")
+
+    def read_u32(self) -> int:
+        return self.read("I")
+
+    def read_i16(self) -> int:
+        return self.read("h")
+
+    def read_i32(self) -> int:
+        return self.read("i")
+
+    def read_f32(self) -> float:
+        return self.read("f")
+
+    def read_rgba(self) -> tuple[int, int, int, int]:
+        return (self.read_u8(), self.read_u8(), self.read_u8(), self.read_u8())
+
+
+def write_u8(f: BinaryIO, v: int):
+    f.write(struct.pack("<B", v))
+
+def write_u16(f: BinaryIO, v: int):
+    f.write(struct.pack("<H", v))
+
+def write_i16(f: BinaryIO, v: int):
+    f.write(struct.pack("<h", v))
+
+def write_u32(f: BinaryIO, v: int):
+    f.write(struct.pack("<I", v))
+
+def write_s32(f: BinaryIO, v: int):
+    f.write(struct.pack("<i", v))
+
+def write_f32(f: BinaryIO, v: float):
+    f.write(struct.pack("<f", v))
+
+def write_rgba(f: BinaryIO, v: tuple[int, int, int, int]):
+    f.write(struct.pack("<BBBB", *v))
+
+def write_f16(f: BinaryIO, v: float):
+    f.write(struct.pack("<e", v))

tfbscript/debug.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass, field
+
+
+def str_set() -> set[str]:
+    return set()
+
+
+@dataclass
+class DebugStore:
+    """
+    Stores debug information while parsing a scirpt
+    """
+
+    unresolved_ops: set[str] = field(default_factory=str_set)

tfbscript/editor/__init__.py

@@ -0,0 +1,3 @@
+from tfbscript.editor.app import open_editor, editor_from_filepath
+
+__all__ = ["open_editor", "editor_from_filepath"]

tfbscript/editor/app.py

@@ -0,0 +1,141 @@
+# pyright: basic
+
+import os
+import signal
+from pathlib import Path
+from typing import cast
+
+from tfbscript.ansi import set_colors_enabled
+from tfbscript.script import ScriptFile
+
+try:
+    from PySide6.QtCore import Qt
+    from PySide6.QtGui import QAction, QFont, QFontDatabase, QKeySequence
+    from PySide6.QtWidgets import (
+        QApplication,
+        QMainWindow,
+        QStyleFactory,
+        QTreeWidget,
+        QVBoxLayout,
+        QWidget,
+        QMessageBox,
+    )
+except ModuleNotFoundError:
+    print("WARN: PySide6 not installed, editor wont work")
+
+from .fonts import register_bold_variant
+from .search import SearchBar, SearchEntry, TreeSearch
+from .style import build_palette, Win98TreeStyle
+from .widgets import populate_tree
+
+import yaml
+
+os.environ.setdefault("QT_ENABLE_HIGHDPI_SCALING", "0")
+os.environ.setdefault("QT_SCALE_FACTOR", "1")
+
+signal.signal(signal.SIGINT, signal.SIG_DFL)
+
+set_colors_enabled(False)
+
+
+def editor_from_filepath(filepath: Path | str):
+    script = ScriptFile.from_path(filepath)
+    open_editor(script)
+
+
+def open_editor(script: ScriptFile):
+    app = cast(QApplication, QApplication.instance()) or QApplication([])
+
+    SCRIPT_DIR = Path(__file__).resolve().parent
+
+    window = QMainWindow()
+    window.setWindowTitle("TFBScript Editor")
+    window.resize(1200, 720)
+
+    app.setStyle(Win98TreeStyle(QStyleFactory.create("Fusion")))
+
+    QFontDatabase.addApplicationFont(
+        str(Path(SCRIPT_DIR, "fonts", "ms-sans-serif", "MS Sans Serif.ttf"))
+    )
+    register_bold_variant(
+        "MS Sans Serif",
+        Path(SCRIPT_DIR, "fonts", "ms-sans-serif-bold", "MS Sans Serif Bold.ttf"),
+    )
+
+    if not Path("EDITOR.yaml").exists():
+        cfg = {"appereance": {"font": "MS Sans Serif"}}
+    else:
+        with open("EDITOR.yaml", "r") as f:
+            cfg = yaml.safe_load(f)
+
+    font_name = cfg.get("appereance", {}).get("font", "MS Sans Serif")
+
+    font = QFont(font_name)
+    font.setPixelSize(13)
+    font.setBold(True)
+    app.setFont(font)
+
+    app.setPalette(build_palette())
+
+    def save() -> None:
+        print("SAVE SAVE SAVE")
+        if script._file_path is not None:
+            with open(
+                script._file_path,
+                "wb",
+            ) as f:
+                script.write(f)
+        else:
+            QMessageBox.critical(None, "Save Failed", "FILE WAS OPENED WITHOUT A _file_path")
+
+    def expand_all() -> None:
+        tree.expandAll()
+
+    file_menu = window.menuBar().addMenu("File")
+    file_menu.addAction("Save").triggered.connect(save)
+
+    other_menu = window.menuBar().addMenu("Other")
+
+    expand_all_action = QAction("Expand All", other_menu)
+
+    expand_all_action.setShortcut(
+        QKeySequence(Qt.KeyboardModifier.ControlModifier | Qt.Key.Key_E)
+    )
+    expand_all_action.triggered.connect(expand_all)
+
+    other_menu.addAction(expand_all_action)
+
+    find_action = QAction("Find", other_menu)
+    find_action.setShortcut(QKeySequence.StandardKey.Find)
+    other_menu.addAction(find_action)
+
+    tree = QTreeWidget()
+    tree.setHeaderHidden(True)
+    tree.setSelectionMode(QTreeWidget.SelectionMode.NoSelection)
+    tree.setFocusPolicy(Qt.FocusPolicy.NoFocus)
+    tree.setRootIsDecorated(True)
+    tree.setItemsExpandable(True)
+    tree.setIndentation(40)
+    tree.itemClicked.connect(
+        lambda item, column: item.setExpanded(not item.isExpanded())
+    )
+
+    search_index: list[SearchEntry] = []
+    for opcode in script.instructions:
+        populate_tree(tree, opcode, search_index)
+
+    search_bar = SearchBar()
+    search = TreeSearch(tree, search_bar, search_index)
+    find_action.triggered.connect(search.open)
+
+    central = QWidget()
+    central_layout = QVBoxLayout(central)
+    central_layout.setContentsMargins(0, 0, 0, 0)
+    central_layout.setSpacing(0)
+    central_layout.addWidget(tree, 1)
+    central_layout.addWidget(search_bar)
+
+    window.setCentralWidget(central)
+    window.show()
+
+    app.exec()

tfbscript/editor/fonts/ms-sans-serif/license.txt

@@ -0,0 +1,4 @@
+The FontStruction “MS Sans Serif”
+(https://fontstruct.com/fontstructions/show/1384746) by “lou” is licensed
+under a Creative Commons Attribution Share Alike license
+(http://creativecommons.org/licenses/by-sa/3.0/).

tfbscript/editor/fonts/ms-sans-serif/readme.txt

@@ -0,0 +1,26 @@
+The font file in this archive was created using Fontstruct the free, online
+font-building tool.
+This font was created by “lou”.
+This font has a homepage where this archive and other versions may be found:
+https://fontstruct.com/fontstructions/show/1384746
+
+Try Fontstruct at http://fontstruct.com
+It’s easy and it’s fun.
+
+NOTE FOR FLASH USERS: Fontstruct fonts (fontstructions) are optimized for Flash.
+If the font in this archive is a pixel font, it is best displayed at a font-size
+of 11.
+
+Fontstruct is sponsored by FontShop.
+Visit them at https://fontshop.com
+FontShop is the original independent font retailer. We’ve been around since
+the dawn of digital type. Whether you need the right font or need to create the
+right font from scratch, let our 26 years of experience work for you.
+
+Fontstruct is copyright ©2017 Rob Meek
+
+LEGAL NOTICE:
+In using this font you must comply with the licensing terms described in the
+file “license.txt” included with this archive.
+If you redistribute the font file in this archive, it must be accompanied by all
+the other files from this archive, including this one.

tfbscript/editor/fonts/ms-sans-serif-bold/license.txt

@@ -0,0 +1,4 @@
+The FontStruction “MS Sans Serif Bold”
+(https://fontstruct.com/fontstructions/show/1384862) by “lou” is licensed
+under a Creative Commons Attribution Share Alike license
+(http://creativecommons.org/licenses/by-sa/3.0/).