mobile-textdb 0.1.0__py3-none-any.whl

mobile_textdb/__init__.py

@@ -0,0 +1,66 @@
+"""
+GTA SA / VC Mobile textdb library (DXT / ETC / PVR).
+
+The game reads ``*.txt``, ``*.dat`` and ``*.toc``. Thumbnail ``*.tmb`` files are
+optional preview caches and are **not** modified by this library.
+
+Quick start::
+
+    from pathlib import Path
+    from PIL import Image
+    from mobile_textdb import TextureDatabase
+
+    db = TextureDatabase.open(Path("textdb/gta3"))
+    db.replace("radar00", Image.open("radar00.png"))
+    db.save()
+"""
+
+from mobile_textdb.codec import (
+    ENCODING_DXT1,
+    ENCODING_DXT5,
+    RLE_SEGMENT_SIZE,
+    build_texture_block,
+    crc_hex,
+    decode_block_pixels,
+    export_texture_png,
+    hash_name,
+    read_dat_block,
+    rle_compress,
+    rle_decompress,
+)
+from mobile_textdb.database import TextureDatabase
+from mobile_textdb.models import (
+    AffiliateEntry,
+    CatEntry,
+    EntryKind,
+    TextureBlock,
+    TextureEntry,
+)
+from mobile_textdb.operations import add_texture_from_image, reassemble_dat
+from mobile_textdb.txd import TxdTexture, load_txd
+
+__all__ = [
+    "AffiliateEntry",
+    "CatEntry",
+    "ENCODING_DXT1",
+    "ENCODING_DXT5",
+    "EntryKind",
+    "RLE_SEGMENT_SIZE",
+    "TextureBlock",
+    "TextureDatabase",
+    "TextureEntry",
+    "TxdTexture",
+    "add_texture_from_image",
+    "build_texture_block",
+    "crc_hex",
+    "decode_block_pixels",
+    "export_texture_png",
+    "hash_name",
+    "load_txd",
+    "read_dat_block",
+    "reassemble_dat",
+    "rle_compress",
+    "rle_decompress",
+]
+
+__version__ = "0.1.0"

mobile_textdb/__main__.py

@@ -0,0 +1,6 @@
+"""GTA Mobile textdb CLI entry point."""
+
+from mobile_textdb.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mobile_textdb/cli.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""CLI for mobile-textdb."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from PIL import Image
+
+from mobile_textdb import TextureDatabase, add_texture_from_image, load_txd
+
+
+def _load_png(path: Path) -> tuple[str, Image.Image]:
+    return path.stem, Image.open(path).convert("RGBA")
+
+
+def _collect_pngs(png_dir: Path, name_prefix: str | None) -> list[tuple[str, Path]]:
+    out: list[tuple[str, Path]] = []
+    for path in sorted(png_dir.glob("*.png")):
+        if name_prefix and not path.stem.startswith(name_prefix):
+            continue
+        out.append((path.stem, path))
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="GTA Mobile textdb texture tool")
+    parser.add_argument("--folder", type=Path, default=Path.cwd(), help="textdb pack folder")
+    parser.add_argument("--format", default="dxt", help="cache extension: dxt, etc, pvr")
+    parser.add_argument("--replace", action="store_true")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--png", type=Path, action="append", default=[])
+    parser.add_argument("--png-dir", type=Path)
+    parser.add_argument("--name-prefix")
+    parser.add_argument("--txd", type=Path, action="append", default=[])
+    parser.add_argument("--alphamode", type=int)
+    args = parser.parse_args(argv)
+
+    folder = args.folder.resolve()
+    db = TextureDatabase.open(folder, format_ext=args.format)
+
+    jobs: list[tuple[str, Image.Image]] = []
+    for png_path in args.png:
+        jobs.append(_load_png(png_path.resolve()))
+    if args.png_dir:
+        for name, path in _collect_pngs(args.png_dir.resolve(), args.name_prefix):
+            jobs.append((name, Image.open(path).convert("RGBA")))
+    for txd_path in args.txd:
+        for tex in load_txd(txd_path.resolve()):
+            jobs.append((tex.name, tex.image))
+
+    if not jobs:
+        parser.error("No textures. Use --png, --png-dir or --txd.")
+
+    added = replaced = skipped = 0
+    for name, img in jobs:
+        try:
+            extra: dict[str, int] = {}
+            if args.alphamode is not None:
+                extra["alphamode"] = args.alphamode
+            elif args.replace and (old := db.get(name)) and "alphamode" in old.props:
+                extra["alphamode"] = int(old.props["alphamode"])
+
+            existed = db.get(name) is not None
+            if args.dry_run:
+                action = "replace" if existed and args.replace else "add"
+                print(f"  PLAN {action}: {name} ({img.width}x{img.height})")
+                if action == "replace":
+                    replaced += 1
+                else:
+                    added += 1
+                continue
+
+            add_texture_from_image(
+                db,
+                name,
+                img,
+                replace=args.replace,
+                extra_props=extra or None,
+            )
+            if existed and args.replace:
+                replaced += 1
+            else:
+                added += 1
+            print(f"  OK {'replace' if existed and args.replace else 'add'}: {name}")
+        except (ValueError, OSError) as exc:
+            skipped += 1
+            print(f"  SKIP {name}: {exc}", file=sys.stderr)
+
+    if args.dry_run:
+        print(f"Dry run: add={added} replace={replaced} skip={skipped}")
+        return 0
+    if added == 0 and replaced == 0:
+        print("Nothing to write.")
+        return 1
+
+    db.save()
+    print(f"Done. add={added} replace={replaced} skip={skipped}")
+    print(f"Wrote {db.paths.txt.name}, {db.paths.dat.name}, {db.paths.toc.name}")
+    return 0 if skipped == 0 else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mobile_textdb/codec.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import struct
+import zlib
+
+from PIL import Image
+import texture2ddecoder as t2d
+
+try:
+    from texfury import BCFormat, Texture
+except ImportError:
+    Texture = None  # type: ignore
+    BCFormat = None  # type: ignore
+
+from mobile_textdb.models import TextureBlock
+
+RLE_SEGMENT_SIZE = 8
+ENCODING_DXT1 = 0x83F0
+ENCODING_DXT5 = 0x83F3
+
+
+def hash_name(name: str) -> int:
+    h = 0
+    for b in name.encode("ascii", errors="replace"):
+        h = (h + ((h << 5) + b)) & 0xFFFFFFFF
+    h = (h + (h >> 5)) & 0xFFFFFFFF
+    return h & 0xFFFF
+
+
+def crc_hex(data: bytes) -> str:
+    return f"{zlib.crc32(data) & 0xFFFFFFFF:08x}"
+
+
+def rle_decompress(data: bytes, segment_size: int, indicator: int) -> bytes:
+    out = bytearray()
+    i = 0
+    while i < len(data):
+        b = data[i]
+        i += 1
+        if b == indicator:
+            rep = data[i]
+            i += 1
+            seg = data[i : i + segment_size]
+            i += segment_size
+            out.extend(seg * rep)
+        else:
+            seg = bytes([b]) + data[i : i + segment_size - 1]
+            i += segment_size - 1
+            out.extend(seg)
+    return bytes(out)
+
+
+def rle_compress(raw: bytes, segment_size: int = RLE_SEGMENT_SIZE) -> tuple[bytes, int]:
+    if len(raw) < segment_size * 4:
+        return raw, 0
+
+    for indicator in (0xFD, 0xFE, 0xFC, 0x01, 0x02, 0x03):
+        if indicator in raw:
+            continue
+        out = bytearray()
+        i = 0
+        while i < len(raw):
+            seg = raw[i : i + segment_size]
+            if len(seg) < segment_size:
+                out.extend(seg)
+                break
+            best_rep = 1
+            while (
+                i + best_rep * segment_size <= len(raw)
+                and raw[i : i + segment_size]
+                == raw[i + best_rep * segment_size : i + (best_rep + 1) * segment_size]
+            ):
+                best_rep += 1
+            if best_rep >= 3:
+                out.append(indicator)
+                out.append(best_rep)
+                out.extend(seg)
+                i += best_rep * segment_size
+            else:
+                out.append(seg[0])
+                out.extend(seg[1:])
+                i += segment_size
+        compressed = bytes(out)
+        if len(compressed) < len(raw):
+            return compressed, indicator
+    return raw, 0
+
+
+def _next_power_of_two(n: int) -> int:
+    p = 1
+    while p < n:
+        p <<= 1
+    return p
+
+
+def resize_to_po2(img: Image.Image, max_size: int | None = None) -> Image.Image:
+    w, h = img.size
+    if max_size:
+        scale = min(1.0, max_size / max(w, h))
+        if scale < 1.0:
+            w = max(1, int(w * scale))
+            h = max(1, int(h * scale))
+            img = img.resize((w, h), Image.Resampling.LANCZOS)
+    w, h = img.size
+    tw, th = _next_power_of_two(w), _next_power_of_two(h)
+    if (tw, th) != (w, h):
+        img = img.resize((tw, th), Image.Resampling.LANCZOS)
+    return img.convert("RGBA")
+
+
+def _compress_dxt(img: Image.Image, use_alpha: bool) -> bytes:
+    if Texture is None:
+        raise RuntimeError("texfury is required: pip install mobile-textdb")
+    fmt = BCFormat.BC3 if use_alpha else BCFormat.BC1
+    return Texture.from_pil(img, format=fmt, generate_mipmaps=False).data
+
+
+def _decode_dxt(encoding: int, width: int, height: int, raw: bytes) -> Image.Image:
+    use_alpha = (encoding & 0xFF) >= 0xF3
+    blocks_w = max(1, width // 4)
+    blocks_h = max(1, height // 4)
+    bpb = 16 if use_alpha else 8
+    need = blocks_w * blocks_h * bpb
+    data = raw[:need]
+    px = t2d.decode_bc3(data, width, height) if use_alpha else t2d.decode_bc1(data, width, height)
+    return Image.frombytes("RGBA", (width, height), px, "raw", "RGBA")
+
+
+def has_visible_alpha(img: Image.Image) -> bool:
+    if img.mode != "RGBA":
+        return False
+    return img.getchannel("A").getextrema()[0] < 255
+
+
+def build_texture_block(img: Image.Image, name: str, use_rle: bool = True) -> TextureBlock:
+    use_alpha = has_visible_alpha(img)
+    raw = _compress_dxt(img, use_alpha)
+    payload, rle_ind = rle_compress(raw) if use_rle else (raw, 0)
+    return TextureBlock(
+        hash=hash_name(name),
+        encoding=ENCODING_DXT5 if use_alpha else ENCODING_DXT1,
+        width=img.width,
+        height=img.height,
+        no_mip=True,
+        payload=payload,
+        rle_indicator=rle_ind,
+    )
+
+
+def read_dat_block(dat: bytes, offset: int) -> TextureBlock:
+    if offset < 0:
+        raise ValueError("affiliate texture has no DAT block")
+    nh, enc, w, hm = struct.unpack_from("<HHHH", dat, offset)
+    cs, rle = struct.unpack_from("<II", dat, offset + 8)
+    height = hm & 0x7FFF
+    payload = dat[offset + 16 : offset + 16 + cs]
+    return TextureBlock(
+        hash=nh,
+        encoding=enc,
+        width=w,
+        height=height,
+        no_mip=bool(hm & 0x8000),
+        payload=payload,
+        rle_indicator=rle,
+    )
+
+
+def decode_block_pixels(block: TextureBlock) -> bytes:
+    raw = block.payload
+    if block.rle_indicator:
+        raw = rle_decompress(raw, RLE_SEGMENT_SIZE, block.rle_indicator & 0xFF)
+    return raw
+
+
+def export_texture_png(block: TextureBlock) -> Image.Image:
+    raw = decode_block_pixels(block)
+    return _decode_dxt(block.encoding, block.width, block.height, raw)
+
+
+def pack_dat_blocks(blocks: list[TextureBlock]) -> bytes:
+    out = bytearray()
+    for i, block in enumerate(blocks):
+        blob = block.to_bytes()
+        if i == 0:
+            out.extend(blob)
+        else:
+            if len(out) < 4:
+                raise ValueError("invalid DAT layout while packing")
+            out[-4:] = blob[:4]
+            out.extend(blob[4:])
+    return bytes(out)

mobile_textdb/database.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterator
+
+from PIL import Image
+
+from mobile_textdb.codec import export_texture_png, read_dat_block
+from mobile_textdb.models import (
+    AffiliateEntry,
+    CatEntry,
+    TextureBlock,
+    TextureDatabasePaths,
+    TextureEntry,
+)
+from mobile_textdb.operations import add_texture_from_image, iter_texture_blocks
+from mobile_textdb.toc import dat_offset_for_entry_index, load_toc, rebuild_toc_from_dat, write_toc
+from mobile_textdb.txt import load_txt, save_txt
+
+
+class TextureDatabase:
+    """Read/write a GTA Mobile texture pack (``*.txt`` + ``*.dat`` + ``*.toc``).
+
+    Thumbnail ``*.tmb`` files are ignored — the game does not require them.
+    """
+
+    def __init__(
+        self,
+        paths: TextureDatabasePaths,
+        entries: list[CatEntry | TextureEntry | AffiliateEntry],
+        dat: bytearray,
+        toc_offsets: list[int],
+    ) -> None:
+        self.paths = paths
+        self.entries = entries
+        self.dat = dat
+        self.toc_offsets = toc_offsets
+
+    @property
+    def name(self) -> str:
+        return self.paths.name
+
+    @property
+    def format_ext(self) -> str:
+        return self.paths.format_ext
+
+    @property
+    def folder(self) -> Path:
+        return self.paths.folder
+
+    @classmethod
+    def open(
+        cls,
+        folder: str | Path,
+        name: str | None = None,
+        *,
+        format_ext: str = "dxt",
+    ) -> TextureDatabase:
+        folder = Path(folder)
+        pack_name = name or folder.name
+        paths = TextureDatabasePaths(folder=folder, name=pack_name, format_ext=format_ext)
+
+        if not paths.txt.is_file():
+            raise FileNotFoundError(paths.txt)
+        if not paths.dat.is_file():
+            raise FileNotFoundError(paths.dat)
+        if not paths.toc.is_file():
+            raise FileNotFoundError(paths.toc)
+
+        dat = bytearray(paths.dat.read_bytes())
+        entries = load_txt(paths.txt)
+        toc_offsets = load_toc(paths.toc, len(dat))
+        if not toc_offsets:
+            toc_offsets = rebuild_toc_from_dat(dat, entries)
+
+        return cls(paths=paths, entries=entries, dat=dat, toc_offsets=toc_offsets)
+
+    def save(self) -> None:
+        """Write ``*.txt``, ``*.dat`` and ``*.toc`` (never touches ``*.tmb``)."""
+        save_txt(self.paths.txt, self.entries)
+        self.paths.dat.write_bytes(self.dat)
+        write_toc(self.paths.toc, len(self.dat), self.toc_offsets)
+
+    def list_textures(self) -> list[str]:
+        return [e.name for e in self.entries if isinstance(e, TextureEntry)]
+
+    def get(self, name: str) -> TextureEntry | None:
+        for entry in self.entries:
+            if isinstance(entry, TextureEntry) and entry.name == name:
+                return entry
+        return None
+
+    def index_of(self, name: str) -> int:
+        for i, entry in enumerate(self.entries):
+            if isinstance(entry, TextureEntry) and entry.name == name:
+                return i
+        raise KeyError(name)
+
+    def read_block(self, name: str) -> TextureBlock:
+        idx = self.index_of(name)
+        off = dat_offset_for_entry_index(idx, self.toc_offsets)
+        return read_dat_block(self.dat, off)
+
+    def export_image(self, name: str) -> Image.Image:
+        return export_texture_png(self.read_block(name))
+
+    def iter_blocks(self) -> Iterator[tuple[TextureEntry, TextureBlock]]:
+        return iter_texture_blocks(self.dat, self.entries, self.toc_offsets)
+
+    def add(
+        self,
+        name: str,
+        image: Image.Image,
+        *,
+        alphamode: int | None = None,
+        extra_props: dict[str, str | int] | None = None,
+        use_rle: bool = True,
+        max_size: int | None = None,
+    ) -> TextureEntry:
+        return add_texture_from_image(
+            self,
+            name,
+            image,
+            replace=False,
+            alphamode=alphamode,
+            extra_props=extra_props,
+            use_rle=use_rle,
+            max_size=max_size,
+        )
+
+    def replace(
+        self,
+        name: str,
+        image: Image.Image,
+        *,
+        alphamode: int | None = None,
+        extra_props: dict[str, str | int] | None = None,
+        use_rle: bool = True,
+        max_size: int | None = None,
+    ) -> TextureEntry:
+        return add_texture_from_image(
+            self,
+            name,
+            image,
+            replace=True,
+            alphamode=alphamode,
+            extra_props=extra_props,
+            use_rle=use_rle,
+            max_size=max_size,
+        )
+
+    def add_or_replace(
+        self,
+        name: str,
+        image: Image.Image,
+        *,
+        replace: bool = False,
+        **kwargs,
+    ) -> TextureEntry:
+        return add_texture_from_image(self, name, image, replace=replace, **kwargs)

mobile_textdb/models.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+
+class EntryKind(Enum):
+    CAT = "cat"
+    TEXTURE = "texture"
+    AFFILIATE = "affiliate"
+
+
+@dataclass
+class CatEntry:
+    kind: EntryKind = EntryKind.CAT
+    line: str = ""
+
+
+@dataclass
+class AffiliateEntry:
+    kind: EntryKind = EntryKind.AFFILIATE
+    name: str = ""
+    affiliate: str = ""
+    raw_line: str = ""
+
+
+@dataclass
+class TextureEntry:
+    kind: EntryKind = EntryKind.TEXTURE
+    name: str = ""
+    width: int = 0
+    height: int = 0
+    props: dict[str, str | int] = field(default_factory=dict)
+    raw_line: str = ""
+
+
+@dataclass
+class TextureBlock:
+    hash: int
+    encoding: int
+    width: int
+    height: int
+    no_mip: bool
+    payload: bytes
+    rle_indicator: int = 0
+
+    @property
+    def height_mask(self) -> int:
+        h = self.height & 0x7FFF
+        return h | (0x8000 if self.no_mip else 0)
+
+    def to_bytes(self) -> bytes:
+        import struct
+
+        header = struct.pack(
+            "<HHHHII",
+            self.hash & 0xFFFF,
+            self.encoding,
+            self.width,
+            self.height_mask,
+            len(self.payload),
+            self.rle_indicator,
+        )
+        return header + self.payload
+
+
+@dataclass
+class TextureDatabasePaths:
+    folder: Path
+    name: str
+    format_ext: str
+
+    @property
+    def txt(self) -> Path:
+        return self.folder / f"{self.name}.txt"
+
+    @property
+    def dat(self) -> Path:
+        return self.folder / f"{self.name}.{self.format_ext}.dat"
+
+    @property
+    def toc(self) -> Path:
+        return self.folder / f"{self.name}.{self.format_ext}.toc"

mobile_textdb/operations.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from typing import Iterator
+
+from PIL import Image
+
+from mobile_textdb.codec import (
+    build_texture_block,
+    crc_hex,
+    decode_block_pixels,
+    export_texture_png,
+    pack_dat_blocks,
+    read_dat_block,
+    resize_to_po2,
+    has_visible_alpha,
+)
+from mobile_textdb.models import TextureBlock, TextureEntry
+from mobile_textdb.toc import dat_offset_for_entry_index, rebuild_toc_from_dat, write_toc
+from mobile_textdb.txt import format_texture_line
+
+
+def iter_texture_blocks(
+    dat: bytes,
+    entries: list,
+    toc_offsets: list[int],
+) -> Iterator[tuple[TextureEntry, TextureBlock]]:
+    for i, entry in enumerate(entries):
+        if not isinstance(entry, TextureEntry):
+            continue
+        off = dat_offset_for_entry_index(i, toc_offsets)
+        if off < 0:
+            continue
+        yield entry, read_dat_block(dat, off)
+
+
+def reassemble_dat(db, new_blocks: dict[str, TextureBlock]) -> None:
+    dat_blocks: list[TextureBlock] = []
+    for entry, block in iter_texture_blocks(db.dat, db.entries, db.toc_offsets):
+        dat_blocks.append(new_blocks.get(entry.name, block))
+    db.dat = bytearray(pack_dat_blocks(dat_blocks))
+    db.toc_offsets = rebuild_toc_from_dat(db.dat, db.entries)
+
+
+def add_texture_from_image(
+    db,
+    name: str,
+    image: Image.Image,
+    *,
+    replace: bool = False,
+    alphamode: int | None = None,
+    extra_props: dict[str, str | int] | None = None,
+    use_rle: bool = True,
+    max_size: int | None = None,
+) -> TextureEntry:
+    image = resize_to_po2(image, max_size)
+    block = build_texture_block(image, name, use_rle=use_rle)
+    img_hash = crc_hex(decode_block_pixels(block))
+
+    existing = db.get(name)
+    if existing and not replace:
+        raise ValueError(f"Texture {name!r} already exists (use replace=True)")
+
+    props: dict[str, str | int] = dict(extra_props or {})
+    if alphamode is not None:
+        props["alphamode"] = alphamode
+    elif has_visible_alpha(image):
+        props.setdefault("alphamode", 2)
+
+    entry = TextureEntry(
+        name=name,
+        width=image.width,
+        height=image.height,
+        props=props,
+        raw_line="",
+    )
+    entry.raw_line = format_texture_line(entry, None, img_hash)
+
+    if existing and replace:
+        idx = db.index_of(name)
+        off = dat_offset_for_entry_index(idx, db.toc_offsets)
+        old = read_dat_block(db.dat, off)
+        if len(block.payload) < len(old.payload):
+            block.payload += b"\x00" * (len(old.payload) - len(block.payload))
+        elif len(block.payload) > len(old.payload):
+            reassemble_dat(db, {name: block})
+            db.entries[idx] = entry
+            return entry
+        new_bytes = block.to_bytes()
+        if len(new_bytes) != len(old.to_bytes()):
+            reassemble_dat(db, {name: block})
+            db.entries[idx] = entry
+            return entry
+        db.dat[off : off + len(new_bytes)] = new_bytes
+        db.entries[idx] = entry
+        return entry
+
+    new_offset = len(db.dat)
+    db.dat.extend(block.to_bytes())
+    db.entries.append(entry)
+    db.toc_offsets.append(new_offset)
+    return entry

mobile_textdb/toc.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+
+from mobile_textdb.codec import read_dat_block
+from mobile_textdb.models import AffiliateEntry, CatEntry, TextureEntry
+
+
+def load_toc(path: Path, dat_size: int) -> list[int]:
+    raw = path.read_bytes()
+    stated = struct.unpack_from("<I", raw, 0)[0]
+    offsets = list(struct.unpack_from("<" + "i" * ((len(raw) - 4) // 4), raw, 4))
+    if stated != dat_size:
+        return []
+    return offsets
+
+
+def dat_offset_for_entry_index(entry_index: int, offsets: list[int]) -> int:
+    if entry_index <= 0:
+        return 0
+    return offsets[entry_index - 1]
+
+
+def write_toc(path: Path, dat_size: int, offsets: list[int]) -> None:
+    header = struct.pack("<I", dat_size)
+    body = struct.pack("<" + "i" * len(offsets), *offsets)
+    path.write_bytes(header + body)
+
+
+def rebuild_toc_from_dat(
+    dat: bytes,
+    entries: list[CatEntry | TextureEntry | AffiliateEntry],
+) -> list[int]:
+    new_offsets: list[int] = []
+    pos = 0
+    for i, entry in enumerate(entries):
+        if i == 0:
+            continue
+        if isinstance(entry, AffiliateEntry):
+            new_offsets.append(-1)
+        elif isinstance(entry, TextureEntry):
+            new_offsets.append(pos)
+            block = read_dat_block(dat, pos)
+            advance = len(block.to_bytes())
+            if any(isinstance(entries[j], TextureEntry) for j in range(i + 1, len(entries))):
+                advance = max(0, advance - 4)
+            pos += advance
+        else:
+            new_offsets.append(-1)
+    return new_offsets

mobile_textdb/txd.py

@@ -0,0 +1,113 @@
+"""Extract textures from GTA SA/VC RenderWare TXD files."""
+
+from __future__ import annotations
+
+import re
+import struct
+from dataclasses import dataclass
+from pathlib import Path
+
+from PIL import Image
+
+D3DFMT_DXT1 = 0x31545844
+D3DFMT_DXT3 = 0x33545844
+D3DFMT_DXT5 = 0x35545844
+D3DFMT_A8R8G8B8 = 0x15
+RW_TEXTURE_NATIVE = 0x15
+
+
+@dataclass
+class TxdTexture:
+    name: str
+    width: int
+    height: int
+    image: Image.Image
+
+
+def _decode_dxt(fmt: int, w: int, h: int, raw: bytes) -> Image.Image:
+    import texture2ddecoder as t2d
+
+    bw, bh = max(1, w // 4), max(1, h // 4)
+    if fmt == D3DFMT_DXT1:
+        px = t2d.decode_bc1(raw[: bw * bh * 8], w, h)
+    elif fmt in (D3DFMT_DXT3, D3DFMT_DXT5):
+        px = t2d.decode_bc3(raw[: bw * bh * 16], w, h)
+    elif fmt == D3DFMT_A8R8G8B8:
+        return Image.frombytes("RGBA", (w, h), raw[: w * h * 4], "raw", "BGRA")
+    else:
+        raise ValueError(f"Unsupported D3D format 0x{fmt:08X}")
+    return Image.frombytes("RGBA", (w, h), px, "raw", "RGBA")
+
+
+def _mip_chain_size(dim: int, bpb: int = 8) -> int:
+    total = 0
+    d = dim
+    while d >= 1:
+        total += max(1, d // 4) ** 2 * bpb
+        d //= 2
+    return total
+
+
+def _infer_dim_from_size(data_len: int, bpb: int = 8) -> int:
+    for dim in (512, 256, 128, 64, 32, 16, 8):
+        if abs(_mip_chain_size(dim, bpb) - data_len) <= 256:
+            return dim
+    for dim in (512, 256, 128, 64, 32, 16, 8):
+        if _mip_chain_size(dim, bpb) <= data_len:
+            return dim
+    return 128
+
+
+def _extract_from_native_body(body: bytes) -> list[TxdTexture]:
+    out: list[TxdTexture] = []
+    pos = 0
+    while True:
+        tag_pos = -1
+        fmt = D3DFMT_DXT1
+        for tag, f in ((b"DXT1", D3DFMT_DXT1), (b"DXT3", D3DFMT_DXT3), (b"DXT5", D3DFMT_DXT5)):
+            p = body.find(tag, pos)
+            if p >= 0 and (tag_pos < 0 or p < tag_pos):
+                tag_pos, fmt = p, f
+        if tag_pos < 0:
+            break
+
+        window = body[max(0, tag_pos - 96) : tag_pos]
+        names_found = re.findall(rb"[\x20-\x7e]{3,48}\x00", window)
+        name = (
+            names_found[-1][:-1].decode("ascii", errors="replace")
+            if names_found
+            else f"texture_{len(out)}"
+        )
+
+        next_tags = [body.find(t, tag_pos + 4) for t in (b"DXT1", b"DXT3", b"DXT5")]
+        next_tags = [t for t in next_tags if t > tag_pos]
+        data_end = min(next_tags) if next_tags else len(body)
+        raw = body[tag_pos + 4 : data_end]
+        bpb = 16 if fmt != D3DFMT_DXT1 else 8
+        dim = _infer_dim_from_size(len(raw), bpb)
+        try:
+            img = _decode_dxt(fmt, dim, dim, raw)
+            out.append(TxdTexture(name=name, width=dim, height=dim, image=img))
+        except Exception:
+            pass
+        pos = tag_pos + 4
+    return out
+
+
+def load_txd(path: str | Path) -> list[TxdTexture]:
+    data = Path(path).read_bytes()
+    textures: list[TxdTexture] = []
+
+    pos = 0
+    while pos + 12 <= len(data):
+        size, ctype, _lib = struct.unpack_from("<III", data, pos)
+        if size < 12:
+            break
+        body = data[pos + 12 : pos + size]
+        if (ctype & 0xFFFF) == RW_TEXTURE_NATIVE:
+            textures.extend(_extract_from_native_body(body))
+        pos += size
+
+    if textures:
+        return textures
+    return _extract_from_native_body(data)

mobile_textdb/txt.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from mobile_textdb.models import AffiliateEntry, CatEntry, TextureEntry
+
+
+def parse_txt_line(line: str) -> CatEntry | TextureEntry | AffiliateEntry | None:
+    line = line.rstrip("\n")
+    if not line.strip():
+        return None
+    if line.startswith("cat="):
+        return CatEntry(line=line)
+
+    m = re.match(r'"([^"]+)"(.*)', line)
+    if not m:
+        return None
+    name, rest = m.group(1), m.group(2).strip()
+
+    if rest.startswith('"affiliate=') or "affiliate=" in rest:
+        aff_m = re.search(r'affiliate=([^\s"]+)', rest)
+        return AffiliateEntry(
+            name=name,
+            affiliate=aff_m.group(1) if aff_m else "",
+            raw_line=line,
+        )
+
+    props: dict[str, str | int] = {}
+    for key, val in re.findall(r"(\w+)=([^\s\"]+)", rest):
+        if key in ("width", "height", "alphamode", "hasdetail", "isdetail", "detailtile", "format"):
+            props[key] = int(val)
+        else:
+            props[key] = val
+
+    if "width" not in props or "height" not in props:
+        return AffiliateEntry(name=name, affiliate=rest, raw_line=line)
+
+    return TextureEntry(
+        name=name,
+        width=int(props["width"]),
+        height=int(props["height"]),
+        props=props,
+        raw_line=line,
+    )
+
+
+def format_texture_line(entry: TextureEntry, png_hash: str | None, img_hash: str) -> str:
+    parts = [f'"{entry.name}"', f"width={entry.width}", f"height={entry.height}"]
+    if png_hash:
+        parts.append(f"png={png_hash}")
+    parts.append(f"img={img_hash}")
+    for key in (
+        "alphamode",
+        "hasdetail",
+        "isdetail",
+        "detailtile",
+        "hassibling",
+        "mipmode",
+        "camnorm",
+        "format",
+        "streammode",
+    ):
+        if key in entry.props:
+            parts.append(f"{key}={entry.props[key]}")
+    return " ".join(parts)
+
+
+def load_txt(path: Path) -> list[CatEntry | TextureEntry | AffiliateEntry]:
+    entries: list[CatEntry | TextureEntry | AffiliateEntry] = []
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        parsed = parse_txt_line(line)
+        if parsed is not None:
+            entries.append(parsed)
+    return entries
+
+
+def save_txt(path: Path, entries: list[CatEntry | TextureEntry | AffiliateEntry]) -> None:
+    lines: list[str] = []
+    for entry in entries:
+        if isinstance(entry, CatEntry):
+            lines.append(entry.line)
+        elif isinstance(entry, AffiliateEntry):
+            lines.append(entry.raw_line)
+        elif isinstance(entry, TextureEntry):
+            lines.append(entry.raw_line)
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")

mobile_textdb-0.1.0.dist-info/METADATA

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: mobile-textdb
+Version: 0.1.0
+Summary: Read/write GTA San Andreas & Vice City mobile texture databases (textdb)
+Author: GTA Mobile modding
+License: MIT
+Keywords: gta,san-andreas,textdb,textures,dxt
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: texture2ddecoder>=1.0.0
+Requires-Dist: texfury>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"

mobile_textdb-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+mobile_textdb/__init__.py,sha256=qRP1yNbh6FqXHIVR6YaymjtAwQ385BMeQT51jE2SmQ0,1486
+mobile_textdb/__main__.py,sha256=DhSSpyXKzDbPcHj9LGEylv1Qz0GV-J7iWpwf4JckZ7k,134
+mobile_textdb/cli.py,sha256=MlFNtNPWXaggq-eVK7xI5D0-yTS1MJ1TNZbdGSndF6k,3748
+mobile_textdb/codec.py,sha256=2k1KFtlltDYWkQMNHy9gWiDknEXujg8sqE-HcO1gGcQ,5682
+mobile_textdb/database.py,sha256=LRs22hhdhl9L_QOyDlq-I5AKMc0rKWwdxBbi519UWCM,4794
+mobile_textdb/models.py,sha256=lKSrpmMq767I5wp5S_ZpQpYyNH1PSUKcrR2xx5GRksM,1682
+mobile_textdb/operations.py,sha256=63juACMKTk-_AjPajoHPngcMykRSuNxPdBbfEukMqfA,3152
+mobile_textdb/toc.py,sha256=kgpGri5gM0gp8DQh-UFghmGdifzL8EXg8j9bzM3DB10,1575
+mobile_textdb/txd.py,sha256=OvuRa27F92Mnq2U2K480KDX1zpSSHqCM224HFpZxj-o,3340
+mobile_textdb/txt.py,sha256=HK-jvs3BuqRlRLmkuL4NPjGvqrpdmMLXHW6cb0Ld_30,2723
+mobile_textdb-0.1.0.dist-info/METADATA,sha256=a3DhsM1lPIokA9i--uy4HyaAp2xsd1iP9h1mtVY8gVc,604
+mobile_textdb-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mobile_textdb-0.1.0.dist-info/entry_points.txt,sha256=wupGx3CJia3vc-hZgjLtKuCMDBapE9fv2yyXEaoy0lY,57
+mobile_textdb-0.1.0.dist-info/top_level.txt,sha256=SuefcasMTy6WDls08fC2lxZUUjgojsFM_Aj4ertBQOM,14
+mobile_textdb-0.1.0.dist-info/RECORD,,

mobile_textdb-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mobile_textdb-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mobile-textdb = mobile_textdb.cli:main

mobile_textdb-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mobile_textdb