dmcsb 0.1.0__py3-none-any.whl

dmcsb/__init__.py

@@ -0,0 +1,50 @@
+"""dmcsb - tools for reverse-engineering Dungeon Master / Chaos Strikes Back data files.
+
+Public API:
+
+    from dmcsb import open_graphics, GraphicsFile, DungeonFile
+
+    g = open_graphics("GRAPHICS.DAT")     # GRAPHICS.DAT -> decoded assets
+    d = DungeonFile().load("DUNGEON.DAT")  # DUNGEON.DAT -> maps / things
+
+See dmcsb.graphics and dmcsb.dungeon for details.
+"""
+
+from .graphics import (
+    GraphicsFile, open_graphics,
+    decode_img1, decode_fnt1, decode_snd2, decode_txt2, decode_lay1,
+    write_wav, lay1_to_text, load_lay1_zones,
+    load_palettes, load_map, item_types_for_count,
+    amiga12_to_rgb, DEFAULT_PALETTE, DEFAULT_SND_RATE,
+    NibbleReader, LAY1_TYPES,
+    __version__,
+)
+from .dungeon import (
+    DungeonFile, open_dungeon, decompress_dungeon,
+    THING_TYPES, THING_NONE, CELL_NAMES, SKILL_NAMES,
+    decode_dungeon_header, decode_map_info,
+    decode_dungeon_text, decode_champion, load_item_names,
+    decode_doorlist, decode_teleporterlist, decode_textstringlist,
+    decode_sensorlist, decode_creaturelist, decode_weaponlist,
+    decode_armorlist, decode_scrolllist, decode_potionlist,
+    decode_containerlist, decode_junklist, decode_projectilelist,
+    decode_explosionlist,
+)
+
+__all__ = [
+    "__version__",
+    "GraphicsFile", "open_graphics", "DungeonFile", "open_dungeon",
+    "decode_img1", "decode_fnt1", "decode_snd2", "decode_txt2", "decode_lay1",
+    "write_wav", "lay1_to_text", "load_lay1_zones",
+    "load_palettes", "load_map", "item_types_for_count",
+    "amiga12_to_rgb", "DEFAULT_PALETTE", "DEFAULT_SND_RATE",
+    "NibbleReader", "LAY1_TYPES",
+    "decompress_dungeon", "THING_TYPES", "THING_NONE", "CELL_NAMES", "SKILL_NAMES",
+    "decode_dungeon_header", "decode_map_info",
+    "decode_dungeon_text", "decode_champion", "load_item_names",
+    "decode_doorlist", "decode_teleporterlist", "decode_textstringlist",
+    "decode_sensorlist", "decode_creaturelist", "decode_weaponlist",
+    "decode_armorlist", "decode_scrolllist", "decode_potionlist",
+    "decode_containerlist", "decode_junklist", "decode_projectilelist",
+    "decode_explosionlist",
+]

dmcsb/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m dmcsb`` -> the dmcsb command-line front-end."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dmcsb/cli.py

@@ -0,0 +1,361 @@
+"""
+dmcsb.cli - command-line front-end for the dmcsb library (``dmcsb`` / ``python -m dmcsb``).
+
+This is the sanctioned presentation layer: the library decoders in dmcsb.graphics /
+dmcsb.dungeon stay silent (no prints), and all human-readable output lives here. The
+``examples/`` scripts are thin shims that import the functions below.
+
+Subcommands:
+    dmcsb dump GRAPHICS.DAT [out_dir] [--map ...] [--palettes ...] [--zones ...]
+    dmcsb dungeon DUNGEON.DAT [--level N]
+    dmcsb uncompress DUNGEON.DAT [output.dat]
+"""
+
+import argparse
+import os
+import re
+import struct
+import sys
+
+from . import (open_graphics, open_dungeon, decompress_dungeon,
+               decode_img1, decode_fnt1, decode_snd2, decode_txt2, decode_lay1,
+               lay1_to_text, load_lay1_zones, write_wav,
+               DEFAULT_PALETTE, SKILL_NAMES)
+from .graphics import _write_png
+
+
+# ---------------------------------------------------------------------------
+# dump - GRAPHICS.DAT -> a folder of PNG/WAV/TXT/.bin + an HTML contact sheet
+# ---------------------------------------------------------------------------
+def _safe(name):
+    return re.sub(r"[^A-Za-z0-9._-]+", "_", name).strip("_")[:80]
+
+
+def dump(path, out_dir="graphics_dump", map_path=None, palettes_path=None,
+         zones_path=None):
+    g = open_graphics(path, map=map_path, palettes=palettes_path, zones=zones_path)
+    os.makedirs(out_dir, exist_ok=True)
+
+    zones = load_lay1_zones(zones_path)   # None -> bundled zones.txt
+    print("Map entries:", len(g.image_map),
+          "| Palettes:", len(g.named_palettes))
+
+    summary = {}        # type -> count
+    failed = []         # (index, reason)
+    images = []         # (index, filename, w, h) for the contact sheet
+    sounds = 0          # SND items exported as WAV
+    texts = 0           # TXT2 items exported as TXT
+    layouts = 0         # LAY1 items exported as JSON
+
+    for i in range(g.item_count):
+        typ = g.item_type(i)
+        summary[typ] = summary.get(typ, 0) + 1
+
+        if typ == "COD":
+            continue                          # copy-protection code, not an image
+
+        try:
+            data = g.item_data(i)             # LZW-decompressed if needed (Atari ST)
+        except NotImplementedError:
+            failed.append((i, "LZW needed (Atari ST) - see _lzw_decompress"))
+            continue
+        except Exception as e:
+            failed.append((i, "item_data: %s" % e))
+            continue
+
+        desc = g.name_for(i)                  # from the map (or None)
+
+        if typ == "IMG1":
+            try:
+                w, h, idx = decode_img1(data)
+                if w == 0 or h == 0:
+                    failed.append((i, "empty image %dx%d" % (w, h)))
+                    continue
+                ipal = g.palette_for(i)
+                rgb = bytearray(w * h * 3)
+                for p, ci in enumerate(idx):
+                    rgb[p * 3:p * 3 + 3] = bytes(ipal[ci & 0xF])
+                tag = "_" + _safe(desc) if desc else ""
+                name = "img_%04d_%dx%d%s.png" % (i, w, h, tag)
+                _write_png(os.path.join(out_dir, name), w, h, bytes(rgb))
+                images.append((i, name, w, h))
+            except Exception as e:
+                failed.append((i, "IMG1 decode: %s" % e))
+        elif typ == "FNT1":
+            try:
+                w, h, idx = decode_fnt1(data)        # 1-bit font -> 0/15
+                rgb = bytearray(w * h * 3)
+                for p, ci in enumerate(idx):
+                    rgb[p * 3:p * 3 + 3] = bytes(DEFAULT_PALETTE[ci & 0xF])
+                tag = "_" + _safe(desc) if desc else ""
+                name = "img_%04d_%dx%d%s.png" % (i, w, h, tag)
+                _write_png(os.path.join(out_dir, name), w, h, bytes(rgb))
+                images.append((i, name, w, h))
+            except Exception as e:
+                failed.append((i, "FNT1 decode: %s" % e))
+        elif typ == "SND":
+            try:
+                pcm = decode_snd2(data)
+                tag = "_" + _safe(desc) if desc else ""
+                name = "snd_%04d%s.wav" % (i, tag)
+                write_wav(os.path.join(out_dir, name), pcm)
+                sounds += 1
+            except Exception as e:
+                failed.append((i, "SND2 decode: %s" % e))
+        elif typ == "TXT2":
+            try:
+                strings = decode_txt2(data)
+                tag = "_" + _safe(desc) if desc else ""
+                name = "txt_%04d%s.txt" % (i, tag)
+                with open(os.path.join(out_dir, name), "w", encoding="utf-8") as f:
+                    f.write("\n".join(strings))
+                texts += 1
+            except Exception as e:
+                failed.append((i, "TXT2 decode: %s" % e))
+        elif typ == "LAY1":
+            # Raw binary = compact form for the engine (parse with decode_lay1).
+            tag = "_" + _safe(desc) if desc else ""
+            with open(os.path.join(out_dir, "lay_%04d%s.bin" % (i, tag)), "wb") as f:
+                f.write(data)
+            # Additionally a READABLE listing annotated with zone names
+            # (for inspection only; zones optional via --zones).
+            with open(os.path.join(out_dir, "lay_%04d%s.txt" % (i, tag)),
+                      "w", encoding="utf-8") as f:
+                f.write(lay1_to_text(decode_lay1(data, zones), zones))
+            layouts += 1
+        else:
+            # Binary tables and others: save the raw data
+            tag = "_" + _safe(desc) if desc else ""
+            name = "%s_%04d%s.bin" % (typ.lower(), i, tag)
+            with open(os.path.join(out_dir, name), "wb") as f:
+                f.write(data)
+
+    _write_contact_sheet(os.path.join(out_dir, "index.html"), images, g)
+    _print_summary(g, summary, failed, images, sounds, texts, layouts, out_dir)
+
+
+def _write_contact_sheet(path, images, g):
+    cells = []
+    for i, name, w, h in images:
+        disp_w = max(w * 2, 48)               # scale up small sprites
+        cells.append(
+            '<figure><img src="%s" width="%d" '
+            'style="image-rendering:pixelated;background:#222;border:1px solid #444">'
+            '<figcaption>#%d &middot; %d&times;%d</figcaption></figure>'
+            % (name, disp_w, i, w, h)
+        )
+    html = (
+        "<!doctype html><meta charset=utf-8>"
+        "<title>GRAPHICS.DAT Dump</title>"
+        "<style>body{background:#111;color:#ccc;font:13px sans-serif;margin:16px}"
+        "figure{display:inline-block;margin:6px;text-align:center;vertical-align:top}"
+        "figcaption{font-size:11px;color:#888;margin-top:2px}</style>"
+        "<h1>GRAPHICS.DAT &mdash; %d images (%s)</h1>%s"
+        % (len(images), g.format, "".join(cells))
+    )
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(html)
+
+
+def _print_summary(g, summary, failed, images, sounds, texts, layouts, out_dir):
+    print("Format:", g.format, "| Items total:", g.item_count)
+    print("Types :", ", ".join("%s=%d" % (t, n) for t, n in sorted(summary.items())))
+    print("Images as PNG:", len(images), "| Sounds as WAV:", sounds,
+          "| Texts as TXT:", texts, "| Layouts (.bin):", layouts)
+    if failed:
+        print("Not decoded:", len(failed))
+        for i, reason in failed[:20]:
+            print("   #%-4d %s" % (i, reason))
+        if len(failed) > 20:
+            print("   ... (%d more)" % (len(failed) - 20))
+    print("Contact sheet ->", os.path.join(out_dir, "index.html"))
+
+
+# ---------------------------------------------------------------------------
+# dungeon - print one DUNGEON.DAT level (map, things, champions)
+# ---------------------------------------------------------------------------
+def print_level(d, level):
+    """Render one dungeon Level: header summary, ornament lists, ASCII tile map."""
+    map_info = d.mapsinfo[str(level)]
+
+    print(f"\nMap at Level {map_info['Level']} ----------------")
+    print(f"  RawMapDataByteOffset: {map_info['RawMapDataByteOffset']}")
+    print(f"  OffsetMapX: {map_info['OffsetMapX']}, OffsetMapY: {map_info['OffsetMapY']}")
+    print(f"  Width: {map_info['Width']}, Height: {map_info['Height']}, Level: {map_info['Level']}")
+    print(f"  RandomFloorOrnamentCount: {map_info['RandomFloorOrnamentCount']}")
+    print(f"  FloorOrnamentCount: {map_info['FloorOrnamentCount']}")
+    print(f"  RandomWallOrnamentCount: {map_info['RandomWallOrnamentCount']}")
+    print(f"  WallOrnamentCount: {map_info['WallOrnamentCount']}")
+    print(f"  Difficulty: {map_info['Difficulty']}")
+    print(f"  CreatureTypeCount: {map_info['CreatureTypeCount']}")
+    print(f"  DoorOrnamentCount: {map_info['DoorOrnamentCount']}")
+    print(f"  DoorSet1: {map_info['DoorSet1']}, DoorSet0: {map_info['DoorSet0']}")
+    print(f"  WallSet: {map_info['WallSet']}, FloorSet: {map_info['FloorSet']}")
+
+    # The ornament/creature index tables sit right after this map's tile grid.
+    w = map_info['Width'] + 1
+    h = map_info['Height'] + 1
+    base = map_info['RawMapDataByteOffset'] + (w * h)
+    counts = [
+        ("Creature", map_info['CreatureTypeCount']),
+        ("WallOrnate", map_info['WallOrnamentCount']),
+        ("FloorOrnate", map_info['FloorOrnamentCount']),
+        ("DoorDeco", map_info['DoorOrnamentCount']),
+    ]
+    print("\nCreatures/Wall/Floor/Doors used ----------------")
+    off = 0
+    parts = []
+    for name, count in counts:
+        vals = "".join(str(d.tile_data[base + off + c]) + ", " for c in range(count))
+        parts.append(f"  {name}: {vals}")
+        off += count
+    print("\n".join(parts) + "\n")
+
+    print("MapData ----------------\n")
+    grid = d.tile_grid(level)
+    lines = []
+    for row in grid:
+        cells = []
+        for val in row:
+            kind = (val >> 5) & 0x7
+            cells.append("  " if kind == 0 else f"{kind} ")
+        lines.append("  " + "".join(cells))
+    print("\n".join(lines))
+
+
+def print_things_on_level(d, level):
+    """Every Thing located on the selected level, grouped by type, with its map
+    (x, y) position. TextString things also show their decoded message."""
+    located = d.located_things(level)
+    grouped = {}
+    for item in located:
+        grouped.setdefault(item["type"], []).append(item)
+    print(f"\nThings on Level {level} ({len(located)}) ----------------")
+    for name, items in grouped.items():
+        print(f"  {name}: {len(items)}")
+        for item in items:
+            pos = f"({item['x']},{item['y']}){item['dir']}"
+            rec = item["thing"]
+            if name == "TextString":
+                label = d.text(rec).replace("\n", " / ")
+            elif name == "Scroll":
+                txt = d.scroll_text(rec)
+                label = txt.replace("\n", " / ") if txt else None
+            else:
+                label = d.item_name(name, rec.get("Type"))
+            line = f"      {pos:>9}  {rec}"
+            if label:
+                line += f"  ->  {label!r}"
+            print(line)
+
+
+def print_champions(d, level):
+    """Champions whose sheet sits on this level (e.g. the Hall of Champions)."""
+    champs = d.champions_on_level(level)
+    if not champs:
+        return
+    print(f"\nChampions on Level {level} ({len(champs)}) ----------------")
+    for c in champs:
+        pos = f"({c['x']},{c['y']}){c['dir']}"
+        title = (" " + c["title"]) if c["title"] else ""
+        print(f"  {pos:>9}  {c['name']}{title} [{c['gender']}]  "
+              f"Health={c['Health']} Stamina={c['Stamina'] // 10} Mana={c['Mana']}  "
+              f"Str={c['Strength']} Dex={c['Dexterity']} Wis={c['Wisdom']} "
+              f"Vit={c['Vitality']} AntiMagic={c['AntiMagic']} AntiFire={c['AntiFire']}")
+        # 16 hidden-skill starting levels, named (SKILL_NAMES[4:] in 4 groups).
+        for gi, basic in enumerate(("Fighter", "Ninja", "Priest", "Wizard")):
+            sub = SKILL_NAMES[4 + gi * 4: 8 + gi * 4]
+            named = " ".join(f"{n}={v}" for n, v in zip(sub, c[basic]))
+            print(f"             {basic:8} {named}")
+
+
+def show_dungeon(path, level):
+    """Load a DUNGEON.DAT and print one level. Returns a process exit code."""
+    d = open_dungeon(path)
+    if str(level) not in d.mapsinfo:
+        levels = ", ".join(sorted(d.mapsinfo, key=int))
+        print(f"No level {level} in this dungeon. Available levels: {levels}")
+        return 1
+    print_level(d, level)
+    print_things_on_level(d, level)
+    print_champions(d, level)
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# uncompress - DUNGEON.DAT -> raw decompressed bytes
+# ---------------------------------------------------------------------------
+def uncompress(in_path, out_path):
+    with open(in_path, "rb") as f:
+        buffer = f.read()
+
+    signature, decompressed_byte_count, _dungeon_id = struct.unpack(">HlH", buffer[:8])
+    if signature == 0x8104:                       # big-endian, compressed
+        data = bytes(decompress_dungeon(buffer[8:], decompressed_byte_count))
+        note = "decompressed %d -> %d bytes" % (len(buffer), len(data))
+    elif signature == 0x0481 or buffer[1] == 0x00:  # little-endian variants
+        print("Little-endian (PC) DUNGEON.DAT is not supported yet.")
+        return 1
+    elif buffer[1] == 0x63:                       # big-endian, already uncompressed
+        data = buffer
+        note = "already uncompressed (%d bytes), copied as-is" % len(buffer)
+    else:
+        print("Not a recognized DUNGEON.DAT file.")
+        return 1
+
+    with open(out_path, "wb") as f:
+        f.write(data)
+    print("%s -> %s (%s)" % (in_path, out_path, note))
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# argparse front-end
+# ---------------------------------------------------------------------------
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="dmcsb",
+        description="Tools for Dungeon Master / Chaos Strikes Back data files.")
+    sub = p.add_subparsers(dest="command", metavar="{dump,dungeon,uncompress}")
+
+    pd = sub.add_parser("dump", help="extract GRAPHICS.DAT to a folder of assets")
+    pd.add_argument("input", metavar="GRAPHICS.DAT")
+    pd.add_argument("out_dir", nargs="?", default="graphics_dump",
+                    help="output directory (default: graphics_dump)")
+    pd.add_argument("--map", dest="map_path", help="override bundled graphics_map.txt")
+    pd.add_argument("--palettes", dest="palettes_path", help="override bundled palettes.txt")
+    pd.add_argument("--zones", dest="zones_path", help="override bundled zones.txt")
+
+    pg = sub.add_parser("dungeon", help="print one DUNGEON.DAT level")
+    pg.add_argument("input", metavar="DUNGEON.DAT")
+    pg.add_argument("--level", type=int, default=1, help="dungeon level (default: 1)")
+
+    pu = sub.add_parser("uncompress", help="write a decompressed copy of DUNGEON.DAT")
+    pu.add_argument("input", metavar="DUNGEON.DAT")
+    pu.add_argument("output", nargs="?",
+                    help="output file (default: <input>.uncompressed)")
+
+    return p
+
+
+def main(argv=None):
+    """Console entry point. Returns a process exit code."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "dump":
+        dump(args.input, args.out_dir, map_path=args.map_path,
+             palettes_path=args.palettes_path, zones_path=args.zones_path)
+        return 0
+    if args.command == "dungeon":
+        return show_dungeon(args.input, args.level)
+    if args.command == "uncompress":
+        out = args.output or args.input + ".uncompressed"
+        return uncompress(args.input, out)
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())