jamesu · August 30, 2026 14:11
diff --git a/extract_volume.py b/extract_volume.py
 #!/usr/bin/env python3
 """Red Baron (RB.EXE) VOLUME.NNN resource extractor.

 Record format (LOCKED, verified against VOLUME.001..007):
    [NAME]\0  [FLAGS k bytes]  [u32le SIZE]  [SIZE payload bytes]
  - SIZE (4-byte little-endian) == exact payload byte length.
  - k (0..8) is a per-record flag-prefix length; found by the rule that SIZE must carry
    you to the next <NAME>\0 (SIZE 4-byte little-endian; for the final record, to EOF).
  - Payloads may be self-delimiting tagged blocks: [TAG "XXXX:"][u24le size][u8 flag][data].
 """
 import sys, re

 NAME_CHARS = set(range(0x20, 0x7F))

 def is_name(b, pos):
    """Return length(incl NUL) of a filename at b[pos], else None."""
    q = pos
    while q < len(b) and b[q] in NAME_CHARS:
        q += 1
    n = b[pos:q]
    if 1 < len(n) < 16 and q < len(b) and b[q] == 0 and re.search(rb'\.[A-Za-z0-9]{1,4}$', n):
        return len(n) + 1
    return None

 def walk(vol):
    """Return [(name, k, size, payload)] for the true record chain."""
    out, pos = [], 0
    while pos < len(vol):
        nl = is_name(vol, pos)
        if nl is None:
            break
        name = vol[pos:pos + nl - 1].decode('latin1')
        body = pos + nl
        choice = None
        for k in range(0, 9):
            if body + k + 4 > len(vol):
                break
            size = int.from_bytes(vol[body + k:body + k + 4], 'little')
            nxt = body + k + 4 + size
            if size <= 0 or nxt > len(vol):
                continue
            if is_name(vol, nxt) is not None:   # lands on the next NAME
                choice = (k, size, nxt)
                break
        if choice is None:
            # terminal record: its SIZE extends to EOF (use k=0, payload = remainder)
            out.append((name, 0, len(vol) - body - 4, vol[body + 4:]))
            break
        k, size, nxt = choice
        out.append((name, k, size, vol[body + k + 4:nxt]))
        pos = nxt
    return out

 TAGS = (b'FNT:', b'BMP:', b'PAL:', b'TTM:', b'SNG:', b'SSM:', b'SCR:', b'OVL:', b'VER:', b'BIN:')

 def parse_blocks(data):
    """Recursively walk tagged blocks -> [(tag, size24, flag, payload)]."""
    out, rest = [], data
    while len(rest) >= 8 and rest[:4] in TAGS:
        tag = rest[:4]
        size = int.from_bytes(rest[4:7], 'little')
        flag = rest[7]
        payload = rest[8:8 + size]
        out.append((tag.decode('latin1', 'replace'), size, flag, payload))
        rest = rest[8 + size:]
    return out

 def main(path, outdir):
    import os
    os.makedirs(outdir, exist_ok=True)
    vol = open(path, 'rb').read()
    total = 0
    for name, k, size, payload in walk(vol):
        safe = re.sub(r'[^A-Za-z0-9_.-]', '_', name)
        with open(os.path.join(outdir, safe), 'wb') as f:
            f.write(payload)
        tags = [t for t, _, _, _ in parse_blocks(payload)]
        print(f"  {name:16s} k={k} size={size:6d} -> {'raw' if not tags else '+'.join(tags)}")
        total += 1
    print(f"wrote {total} resources -> {outdir}")

 if __name__ == '__main__':
    if len(sys.argv) < 2:
        print("usage: extract_volume.py VOLUME.NNN [outdir]"); sys.exit(1)
    main(sys.argv[1], sys.argv[2] if len(sys.argv) > 2 else 'extracted_' + sys.argv[1].split('/')[-1])
diff --git a/RedBaron3SpaceDos.md b/RedBaron3SpaceDos.md
diff --git a/RedBaron3SpaceMac.md b/RedBaron3SpaceMac.md
diff --git a/redbaron_dos_model_to_obj.py b/redbaron_dos_model_to_obj.py
 #!/usr/bin/env python3
 """Export DOS Red Baron TBL geometry using the PS.EXE table hierarchy.

 This exporter intentionally does not scan for records and does not use CLG to
 discover geometry.  Offsets and counts are taken from the TBL itself:

  root -> detail entries -> part entries -> variants -> polygon records

 Only type-0 polygon primitives are representable as native OBJ geometry.
 Type-1 spheres and type-2/3 bitmap primitives are reported in the OBJ
 comments and skipped as surface geometry.
 """

 from __future__ import annotations

 import argparse
 import struct
 from pathlib import Path


 def u16(data: bytes, offset: int) -> int:
    return struct.unpack_from("<H", data, offset)[0]


 def i16(data: bytes, offset: int) -> int:
    return struct.unpack_from("<h", data, offset)[0]


 def checked_range(data: bytes, offset: int, size: int, label: str) -> None:
    if offset < 0 or size < 0 or offset + size > len(data):
        raise ValueError(f"{label} outside file: 0x{offset:x}+0x{size:x}")


 def parse(tbl: Path):
    data = tbl.read_bytes()
    checked_range(data, 0, 2, "root pointer")
    root = u16(data, 0)
    checked_range(data, root, 16, "shape header")
    detail_count = u16(data, root + 0x0c)
    detail_offset = u16(data, root + 0x0e)
    checked_range(data, detail_offset, detail_count * 6, "detail array")

    details = []
    for detail_index in range(detail_count):
        at = detail_offset + detail_index * 6
        threshold = u16(data, at)
        flags = data[at + 2]
        part_count = data[at + 3]
        part_offset = u16(data, at + 4)
        checked_range(data, part_offset, part_count * 10,
                      f"detail {detail_index} part array")
        parts = []
        for part_index in range(part_count):
            p = part_offset + part_index * 10
            animation_offset = i16(data, p)
            point_selector = data[p + 2]
            point_count = data[p + 3]
            point_pool_offset = u16(data, p + 4)
            variant_count = u16(data, p + 6)
            variant_offset = u16(data, p + 8)
            checked_range(data, point_pool_offset, point_count * 6,
                          f"detail {detail_index} part {part_index} point pool")
            checked_range(data, variant_offset, variant_count * 7,
                          f"detail {detail_index} part {part_index} variants")
            parts.append({
                "animation_offset": animation_offset,
                "point_selector": point_selector,
                "point_count": point_count,
                "point_pool_offset": point_pool_offset,
                "variant_count": variant_count,
                "variant_offset": variant_offset,
            })
        details.append({
            "threshold": threshold,
            "flags": flags,
            "part_offset": part_offset,
            "parts": parts,
        })
    return data, root, details


 def selector_stream(data: bytes, offset: int):
    if offset >= len(data):
        raise ValueError(f"selector stream outside file: 0x{offset:x}")
    end = data.find(b"\xff", offset)
    if end < 0:
        raise ValueError(f"unterminated selector stream: 0x{offset:x}")
    return list(data[offset:end])


 def export(tbl: Path, out: Path, scale: float) -> tuple[int, int, int, int, int]:
    data, root, details = parse(tbl)
    lines = [
        f"# Structured DOS TBL export: {tbl.name}",
        "# Hierarchy: root -> details -> parts -> variants -> polygon records",
        "# Coordinates: signed little-endian i16 XYZ from each part-local pool",
        f"# Coordinate scale: {scale:g}",
        f"# root=0x{root:04x} details={len(details)}",
    ]
    vertex_count = face_count = line_count = skipped = 0
    vertex_ids = {}

    def vertex(part, selector):
        nonlocal vertex_count
        key = (part["point_pool_offset"], selector)
        if key in vertex_ids:
            return vertex_ids[key]
        if selector >= part["point_count"]:
            raise ValueError(f"selector {selector} exceeds point count "
                             f"{part['point_count']}")
        at = part["point_pool_offset"] + selector * 6
        xyz = (i16(data, at), i16(data, at + 2), i16(data, at + 4))
        vertex_count += 1
        vertex_ids[key] = vertex_count
        lines.append("v %.6f %.6f %.6f # pool=0x%04x selector=0x%02x" %
                     (xyz[0] * scale, xyz[1] * scale, xyz[2] * scale,
                      part["point_pool_offset"], selector))
        return vertex_count

    for detail_index, detail in enumerate(details):
        for part_index, part in enumerate(detail["parts"]):
            for variant_index in range(part["variant_count"]):
                at = part["variant_offset"] + variant_index * 7
                primitive_type = data[at]
                name = (f"detail_{detail_index:02d}_part_{part_index:03d}_"
                        f"frame_{variant_index:03d}")
                lines.append(f"o {name}")
                lines.append(
                    "# threshold=%d flags=0x%02x part_offset=0x%04x "
                    "point_pool=0x%04x point_count=%d animation_offset=%d" %
                    (detail["threshold"], detail["flags"], detail["part_offset"],
                     part["point_pool_offset"], part["point_count"],
                     part["animation_offset"]))
                lines.append(f"# frame_variant={variant_index} variant_offset=0x{at:04x} type={primitive_type}")

                if primitive_type != 0:
                    skipped += 1
                    kind = {1: "sphere", 2: "bitmap", 3: "point_bitmap"}.get(
                        primitive_type, "unknown")
                    lines.append(f"# skipped non-OBJ primitive: {kind}")
                    continue

                polygon_count = u16(data, at + 1)
                polygon_offset = u16(data, at + 3)
                checked_range(data, polygon_offset, polygon_count * 8,
                              f"variant 0x{at:x} polygon list")
                lines.append(
                    f"# polygon_count={polygon_count} polygon_offset=0x{polygon_offset:04x}")
                for polygon_index in range(polygon_count):
                    p = polygon_offset + polygon_index * 8
                    flags = data[p]
                    selectors_offset = u16(data, p + 6)
                    selectors = selector_stream(data, selectors_offset)
                    if len(selectors) < 2:
                        skipped += 1
                        continue
                    indices = [vertex(part, selector) for selector in selectors]
                    lines.append(
                        f"# polygon={polygon_index} record=0x{p:04x} "
                        f"flags=0x{flags:02x} selectors=" +
                        " ".join(f"0x{x:02x}" for x in selectors))
                    if len(indices) == 2:
                        lines.append("l " + " ".join(map(str, indices)))
                        line_count += 1
                    else:
                        lines.append("f " + " ".join(map(str, indices)))
                        face_count += 1

    out.parent.mkdir(parents=True, exist_ok=True)
    out.write_text("\n".join(lines) + "\n")
    return len(details), vertex_count, face_count, line_count, skipped


 def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument("tbl", type=Path)
    ap.add_argument("-o", "--out", type=Path, required=True)
    ap.add_argument("--scale", type=float, default=1.0 / 256.0,
                    help="scale raw XYZ values for OBJ (default: 1/256)")
    args = ap.parse_args()
    try:
        details, vertices, faces, lines, skipped = export(
            args.tbl, args.out, args.scale)
    except (OSError, ValueError, struct.error) as exc:
        ap.error(str(exc))
    print(f"{args.tbl.name}: details={details} vertices={vertices} "
          f"faces={faces} lines={lines} skipped={skipped} -> {args.out}")
    return 0


 if __name__ == "__main__":
    raise SystemExit(main())
diff --git a/redbaron_mac_model_to_obj.py b/redbaron_mac_model_to_obj.py
 #!/usr/bin/env python3
 """Self-contained Mac Red Baron package-to-OBJ diagnostic exporter.

 This file intentionally imports no project modules.  It contains the small
 amount of TBL/DAT/CLG parsing needed by the package exporter, including the
 detail/part/frame/draw names, filters, and metadata report.
 """
 from __future__ import annotations

 import argparse
 import struct
 from pathlib import Path

 RAW_TYPES = {0x80, 0x81, 0xA0, 0xA1}


 def be16(data, off):
    return int.from_bytes(data[off:off + 2], "big")


 def tbl_dat(path):
    raw = Path(path).read_bytes()
    q = 0
    while q + 8 <= len(raw):
        tag = raw[q:q + 4]
        size = int.from_bytes(raw[q + 4:q + 7], "little")
        end = q + 8 + size
        if end > len(raw):
            raise ValueError("truncated TBL chunk")
        if tag == b"DAT:":
            return raw[q + 8:end]
        q = end
    raise ValueError("TBL has no DAT chunk")


 def validate_clg(path):
    """Validate the matching six-group CLG framing and byte order."""
    raw = Path(path).read_bytes()
    if len(raw) < 12:
        raise ValueError("CLG is shorter than its six group counts")
    counts = struct.unpack_from(">6H", raw, 0)
    expected = 12 + 2 * sum(counts)
    if len(raw) != expected:
        raise ValueError("CLG size does not match its six big-endian counts")


 def raw_record(data, off):
    if off < 0 or off + 8 > len(data) or data[off] not in RAW_TYPES:
        return None
    return {"offset": off, "type": data[off],
            "bytes": data[off:off + 8].hex(" "),
            "link": be16(data, off + 6)}


 def streams(data, records):
    out = []
    seen = set()
    for rec in records:
        start = rec["link"] + 8
        if not 0 <= start < len(data):
            continue
        end = data.find(b"\xff", start)
        if end < 0 or (start, end) in seen:
            continue
        seen.add((start, end))
        out.append({"source_record": rec["offset"],
                    "record_type": "0x%02x" % rec["type"],
                    "offset": start, "values": list(data[start:end]),
                    "terminator_offset": end})
    return out


 def is_group(data, off):
    return 0 <= off and off + 8 <= len(data) and data[off:off + 3] == b"\0\0\0"


 def raw_group(data, off):
    """Read the observed group-header/linked-record forms."""
    if not is_group(data, off):
        return None
    count = be16(data, off + 2)
    anchor = be16(data, off + 4)
    if anchor != off and (is_group(data, anchor) or
                          raw_record(data, anchor) is not None):
        child = anchor
    else:
        child = off + 8

    # Most groups are a contiguous record chain.  Some encode one initial
    # record plus count more records, so try that form first.
    for amount, layout in ((count + 1, "initial_plus_count_contiguous"),
                           (count, "contiguous")):
        if amount <= 0:
            continue
        recs = [raw_record(data, child + i * 8) for i in range(amount)]
        if all(recs):
            return {"count": count, "anchor": anchor, "child": child,
                    "records": recs, "record_layout": layout,
                    "streams": streams(data, recs)}

    # Another observed form has one record whose link points back to itself,
    # followed by a terminated inline stream and then the remaining records.
    first = raw_record(data, child)
    if count and first is not None and first["link"] == child:
        end = data.find(b"\xff", child + 8)
        after = len(data) if end < 0 else end + 1
        if after < len(data) and data[after] == 0:
            after += 1
        trailing = [raw_record(data, after + i * 8) for i in range(count)]
        if end >= 0 and all(trailing):
            recs = [first] + trailing
            return {"count": count, "anchor": anchor, "child": child,
                    "records": recs,
                    "record_layout": "initial_inline_plus_count_contiguous",
                    "streams": streams(data, recs)}

    # Otherwise follow links.  Stop when the declared count is reached.
    recs = []
    q = child
    seen = set()
    for _ in range(count + 1):
        if q in seen:
            break
        seen.add(q)
        rec = raw_record(data, q)
        if rec is None:
            break
        recs.append(rec)
        nxt = rec["link"]
        if len(recs) >= count:
            break
        if nxt == q:
            end = data.find(b"\xff", q + 8)
            q = len(data) if end < 0 else end + 1
            if q < len(data) and data[q] == 0:
                q += 1
        else:
            q = nxt
    if not recs:
        return None
    return {"count": count, "anchor": anchor, "child": child,
            "records": recs, "record_layout": "linked_or_inline",
            "streams": streams(data, recs)}


 def group_for_target(data, target):
    """Resolve a draw target using declared offsets only.

    There is deliberately no nearby-byte search here.  The executable-style
    walk uses the known target, the fixed +8 envelope, the group anchor, the
    declared count, and each record's link.
    """
    group = raw_group(data, target + 8)
    if group is not None:
        return group
    return None


 def frame_streams(data, entry, root, frame, include_auxiliary):
    """Read one executable-selected per-part frame from the loaded DAT."""
    period = entry["cell_period"]
    draw_base = root + entry["draw_target"]
    if frame < 0 or frame >= period or draw_base + frame * 8 + 8 > len(data):
        return None, []
    draw_off = draw_base + frame * 8
    if data[draw_off] != 0:
        return draw_off, []
    count = be16(data, draw_off + 2)
    command_base = root + be16(data, draw_off + 4)
    result = []
    for command_number in range(count):
        command_off = command_base + command_number * 8
        if command_off + 8 > len(data):
            break
        command_type = data[command_off]
        start = root + be16(data, command_off + 6)
        if not 0 <= start < len(data):
            continue
        end = data.find(b"\xff", start)
        if end < 0 or (not include_auxiliary and command_type not in (0xa0, 0xa1)):
            continue
        result.append({"frame": frame, "draw_offset": draw_off,
                       "command_number": command_number,
                       "source_record": command_off,
                       "record_type": "0x%02x" % command_type,
                       "offset": start, "values": list(data[start:end])})
    return draw_off, result


 def package_entries(data):
    """Read the repeated root directory and its 14-byte entries."""
    if len(data) < 16 or int.from_bytes(data[0:4], "big") != 8:
        raise ValueError("DAT does not begin with the expected root pointer")
    root = 8
    entries_by_detail = []
    detail_count = be16(data, root + 8)
    detail_offset = be16(data, root + 0xa)
    q = root + detail_offset
    descriptors = []
    for _ in range(detail_count):
        if q + 6 > len(data):
            break
        kind = be16(data, q)
        count = be16(data, q + 2)
        descriptors.append((kind, count, root + be16(data, q + 4)))
        q += 6

    for kind, count, target in descriptors:
        if target < 0 or target + count * 14 > len(data):
            continue
        entries = []
        for index in range(count):
            off = target + index * 14
            words = [be16(data, off + i) for i in range(0, 14, 2)]
            entries.append({"index": index, "offset": off,
                            "state_channel": data[off],
                            "point_target": words[2],
                            "cell_period": words[3],
                            "draw_target": words[4]})
        entries_by_detail.append({"raw_key": kind, "entries": entries})
    return entries_by_detail


 def point_values(data, base, selectors):
    if not selectors or base < 0:
        return None
    end = base + 6 * max(selectors) + 6
    if end > len(data):
        return None
    return [struct.unpack_from(">hhh", data, base + 6 * value)
            for value in selectors]


 def selected_streams(data, entry, include_aux):
    group = group_for_target(data, entry["draw_target"])
    if group is None:
        return None, []
    result = streams(data, group["records"])
    if not include_aux:
        result = [s for s in result if s["record_type"] in ("0xa0", "0xa1")]
    return group, result


 def metadata(data, sections, include_aux):
    lines = ["Model metadata", "===============",
             "detail levels: %d" % len(sections)]
    for detail, section in enumerate(sections):
        lines.append("detail %d (raw key 0x%02x): %d parts" %
                     (detail, section["raw_key"], len(section["entries"])))
        for part, entry in enumerate(section["entries"]):
            lines.append("  part %d: %d frames, channel=%d, point=0x%04x frame_table=0x%04x" %
                         (part, entry["cell_period"], entry["state_channel"],
                          entry["point_target"], entry["draw_target"]))
            for frame in range(entry["cell_period"]):
                draw_off, frame_items = frame_streams(data, entry, 8, frame,
                                                      include_aux)
                lines.append("    frame %d: draw=0x%04x commands=%d" %
                             (frame, draw_off or 0, len(frame_items)))
                for draw, stream in enumerate(frame_items):
                    lines.append("      draw %d: type=%s selectors=%d source=0x%04x stream=0x%04x" %
                                 (draw, stream["record_type"], len(stream["values"]),
                                  stream["source_record"], stream["offset"]))
    return lines


 def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("tbl", type=Path)
    ap.add_argument("--clg", type=Path,
                    help="matching CLG; accepted for validating the pair")
    ap.add_argument("-o", "--out", type=Path)
    ap.add_argument("--scale", type=float, default=256.0)
    ap.add_argument("--point-header", type=int, default=8)
    ap.add_argument("--include-auxiliary", action="store_true")
    ap.add_argument("--section-key", type=lambda value: int(value, 0))
    ap.add_argument("--detail-level", "--detail", type=int)
    ap.add_argument("--part-number", "--part", type=int)
    ap.add_argument("--subpart-number", "--subpart", "--draw-record",
                    dest="subpart_number", type=int,
                    help="export only this zero-based draw command within each frame")
    ap.add_argument("--frame-number", "--frame", type=int,
                    help="export only this zero-based per-part frame")
    ap.add_argument("--metadata", action="store_true")
    args = ap.parse_args()

    clg = args.clg or args.tbl.with_suffix(".CLG")
    if not clg.exists():
        raise ValueError("CLG file does not exist: %s" % clg)
    validate_clg(clg)
    data = tbl_dat(args.tbl)
    sections = package_entries(data)
    if args.metadata:
        print("\n".join(metadata(data, sections, args.include_auxiliary)))
        print()

    lines = ["# Red Baron Mac package export",
             "# coordinates: signed big-endian i16 XYZ, runtime scale / %g" % args.scale,
             "# object name: detail_<level>_part_<number>_frame_<number>",
             "# frame is a selectable per-part visual state; its draw commands follow"]
    vcount = fcount = lcount = ocount = skipped = 0
    for detail, section in enumerate(sections):
        if args.detail_level is not None and detail != args.detail_level:
            continue
        if args.section_key is not None and section["raw_key"] != args.section_key:
            continue
        for part, entry in enumerate(section["entries"]):
            if args.part_number is not None and part != args.part_number:
                continue
            base = entry["point_target"] + args.point_header
            for frame in range(entry["cell_period"]):
                if args.frame_number is not None and frame != args.frame_number:
                    continue
                draw_off, frame_items = frame_streams(
                    data, entry, 8, frame, args.include_auxiliary)
                if draw_off is None:
                    skipped += 1
                    continue
                geometry = []
                for draw, stream in enumerate(frame_items):
                    if args.subpart_number is not None and draw != args.subpart_number:
                        continue
                    values = tuple(stream["values"])
                    if len(values) < (2 if args.include_auxiliary else 3):
                        continue
                    xyz = point_values(data, base, values)
                    if xyz is None:
                        skipped += 1
                        continue
                    geometry.append((draw, stream, xyz, values))
                if not geometry:
                    continue
                name = "detail_%02d_part_%03d_frame_%03d" % (
                    detail, part, frame)
                lines.append("o " + name)
                lines.append("# detail=%d raw_section_key=0x%02x part=%d frame=%d draw_commands=%d point_base=0x%04x" %
                             (detail, section["raw_key"], part, frame,
                              len(geometry), base))
                for draw, stream, xyz, values in geometry:
                    lines.append("# draw=%d record_type=%s record=0x%04x stream=0x%04x selectors=%s" %
                                 (draw, stream["record_type"], stream["source_record"],
                                  stream["offset"], ",".join("%02x" % value for value in values)))
                    for x, y, z in xyz:
                        lines.append("v %.6f %.6f %.6f" %
                                     (x / args.scale, y / args.scale, z / args.scale))
                    first = vcount + 1
                    indices = [str(first + i) for i in range(len(xyz))]
                    if len(indices) == 2:
                        lines.append("l " + " ".join(indices))
                        lcount += 1
                    else:
                        lines.append("f " + " ".join(indices))
                        fcount += 1
                    vcount += len(xyz)
                ocount += 1

    out = args.out or args.tbl.with_suffix(".package.obj")
    out.write_text("\n".join(lines) + "\n")
    print("wrote %s" % out)
    print("objects=%d faces=%d lines=%d vertices=%d skipped=%d" %
          (ocount, fcount, lcount, vcount, skipped))


 if __name__ == "__main__":
    main()
diff --git a/RedBaronVolumeFiles.md b/RedBaronVolumeFiles.md
	#!/usr/bin/env python3
	"""Red Baron (RB.EXE) VOLUME.NNN resource extractor.

	Record format (LOCKED, verified against VOLUME.001..007):
	[NAME]\0 [FLAGS k bytes] [u32le SIZE] [SIZE payload bytes]
	- SIZE (4-byte little-endian) == exact payload byte length.
	- k (0..8) is a per-record flag-prefix length; found by the rule that SIZE must carry
	you to the next <NAME>\0 (SIZE 4-byte little-endian; for the final record, to EOF).
	- Payloads may be self-delimiting tagged blocks: [TAG "XXXX:"][u24le size][u8 flag][data].
	"""
	import sys, re

	NAME_CHARS = set(range(0x20, 0x7F))

	def is_name(b, pos):
	"""Return length(incl NUL) of a filename at b[pos], else None."""
	q = pos
	while q < len(b) and b[q] in NAME_CHARS:
	q += 1
	n = b[pos:q]
	if 1 < len(n) < 16 and q < len(b) and b[q] == 0 and re.search(rb'\.[A-Za-z0-9]{1,4}$', n):
	return len(n) + 1
	return None

	def walk(vol):
	"""Return [(name, k, size, payload)] for the true record chain."""
	out, pos = [], 0
	while pos < len(vol):
	nl = is_name(vol, pos)
	if nl is None:
	break
	name = vol[pos:pos + nl - 1].decode('latin1')
	body = pos + nl
	choice = None
	for k in range(0, 9):
	if body + k + 4 > len(vol):
	break
	size = int.from_bytes(vol[body + k:body + k + 4], 'little')
	nxt = body + k + 4 + size
	if size <= 0 or nxt > len(vol):
	continue
	if is_name(vol, nxt) is not None: # lands on the next NAME
	choice = (k, size, nxt)
	break
	if choice is None:
	# terminal record: its SIZE extends to EOF (use k=0, payload = remainder)
	out.append((name, 0, len(vol) - body - 4, vol[body + 4:]))
	break
	k, size, nxt = choice
	out.append((name, k, size, vol[body + k + 4:nxt]))
	pos = nxt
	return out

	TAGS = (b'FNT:', b'BMP:', b'PAL:', b'TTM:', b'SNG:', b'SSM:', b'SCR:', b'OVL:', b'VER:', b'BIN:')

	def parse_blocks(data):
	"""Recursively walk tagged blocks -> [(tag, size24, flag, payload)]."""
	out, rest = [], data
	while len(rest) >= 8 and rest[:4] in TAGS:
	tag = rest[:4]
	size = int.from_bytes(rest[4:7], 'little')
	flag = rest[7]
	payload = rest[8:8 + size]
	out.append((tag.decode('latin1', 'replace'), size, flag, payload))
	rest = rest[8 + size:]
	return out

	def main(path, outdir):
	import os
	os.makedirs(outdir, exist_ok=True)
	vol = open(path, 'rb').read()
	total = 0
	for name, k, size, payload in walk(vol):
	safe = re.sub(r'[^A-Za-z0-9_.-]', '_', name)
	with open(os.path.join(outdir, safe), 'wb') as f:
	f.write(payload)
	tags = [t for t, _, _, _ in parse_blocks(payload)]
	print(f" {name:16s} k={k} size={size:6d} -> {'raw' if not tags else '+'.join(tags)}")
	total += 1
	print(f"wrote {total} resources -> {outdir}")

	if __name__ == '__main__':
	if len(sys.argv) < 2:
	print("usage: extract_volume.py VOLUME.NNN [outdir]"); sys.exit(1)
	main(sys.argv[1], sys.argv[2] if len(sys.argv) > 2 else 'extracted_' + sys.argv[1].split('/')[-1])
	#!/usr/bin/env python3
	"""Export DOS Red Baron TBL geometry using the PS.EXE table hierarchy.

	This exporter intentionally does not scan for records and does not use CLG to
	discover geometry. Offsets and counts are taken from the TBL itself:

	root -> detail entries -> part entries -> variants -> polygon records

	Only type-0 polygon primitives are representable as native OBJ geometry.
	Type-1 spheres and type-2/3 bitmap primitives are reported in the OBJ
	comments and skipped as surface geometry.
	"""

	from __future__ import annotations

	import argparse
	import struct
	from pathlib import Path


	def u16(data: bytes, offset: int) -> int:
	return struct.unpack_from("<H", data, offset)[0]


	def i16(data: bytes, offset: int) -> int:
	return struct.unpack_from("<h", data, offset)[0]


	def checked_range(data: bytes, offset: int, size: int, label: str) -> None:
	if offset < 0 or size < 0 or offset + size > len(data):
	raise ValueError(f"{label} outside file: 0x{offset:x}+0x{size:x}")


	def parse(tbl: Path):
	data = tbl.read_bytes()
	checked_range(data, 0, 2, "root pointer")
	root = u16(data, 0)
	checked_range(data, root, 16, "shape header")
	detail_count = u16(data, root + 0x0c)
	detail_offset = u16(data, root + 0x0e)
	checked_range(data, detail_offset, detail_count * 6, "detail array")

	details = []
	for detail_index in range(detail_count):
	at = detail_offset + detail_index * 6
	threshold = u16(data, at)
	flags = data[at + 2]
	part_count = data[at + 3]
	part_offset = u16(data, at + 4)
	checked_range(data, part_offset, part_count * 10,
	f"detail {detail_index} part array")
	parts = []
	for part_index in range(part_count):
	p = part_offset + part_index * 10
	animation_offset = i16(data, p)
	point_selector = data[p + 2]
	point_count = data[p + 3]
	point_pool_offset = u16(data, p + 4)
	variant_count = u16(data, p + 6)
	variant_offset = u16(data, p + 8)
	checked_range(data, point_pool_offset, point_count * 6,
	f"detail {detail_index} part {part_index} point pool")
	checked_range(data, variant_offset, variant_count * 7,
	f"detail {detail_index} part {part_index} variants")
	parts.append({
	"animation_offset": animation_offset,
	"point_selector": point_selector,
	"point_count": point_count,
	"point_pool_offset": point_pool_offset,
	"variant_count": variant_count,
	"variant_offset": variant_offset,
	})
	details.append({
	"threshold": threshold,
	"flags": flags,
	"part_offset": part_offset,
	"parts": parts,
	})
	return data, root, details


	def selector_stream(data: bytes, offset: int):
	if offset >= len(data):
	raise ValueError(f"selector stream outside file: 0x{offset:x}")
	end = data.find(b"\xff", offset)
	if end < 0:
	raise ValueError(f"unterminated selector stream: 0x{offset:x}")
	return list(data[offset:end])


	def export(tbl: Path, out: Path, scale: float) -> tuple[int, int, int, int, int]:
	data, root, details = parse(tbl)
	lines = [
	f"# Structured DOS TBL export: {tbl.name}",
	"# Hierarchy: root -> details -> parts -> variants -> polygon records",
	"# Coordinates: signed little-endian i16 XYZ from each part-local pool",
	f"# Coordinate scale: {scale:g}",
	f"# root=0x{root:04x} details={len(details)}",
	]
	vertex_count = face_count = line_count = skipped = 0
	vertex_ids = {}

	def vertex(part, selector):
	nonlocal vertex_count
	key = (part["point_pool_offset"], selector)
	if key in vertex_ids:
	return vertex_ids[key]
	if selector >= part["point_count"]:
	raise ValueError(f"selector {selector} exceeds point count "
	f"{part['point_count']}")
	at = part["point_pool_offset"] + selector * 6
	xyz = (i16(data, at), i16(data, at + 2), i16(data, at + 4))
	vertex_count += 1
	vertex_ids[key] = vertex_count
	lines.append("v %.6f %.6f %.6f # pool=0x%04x selector=0x%02x" %
	(xyz[0] * scale, xyz[1] * scale, xyz[2] * scale,
	part["point_pool_offset"], selector))
	return vertex_count

	for detail_index, detail in enumerate(details):
	for part_index, part in enumerate(detail["parts"]):
	for variant_index in range(part["variant_count"]):
	at = part["variant_offset"] + variant_index * 7
	primitive_type = data[at]
	name = (f"detail_{detail_index:02d}_part_{part_index:03d}_"
	f"frame_{variant_index:03d}")
	lines.append(f"o {name}")
	lines.append(
	"# threshold=%d flags=0x%02x part_offset=0x%04x "
	"point_pool=0x%04x point_count=%d animation_offset=%d" %
	(detail["threshold"], detail["flags"], detail["part_offset"],
	part["point_pool_offset"], part["point_count"],
	part["animation_offset"]))
	lines.append(f"# frame_variant={variant_index} variant_offset=0x{at:04x} type={primitive_type}")

	if primitive_type != 0:
	skipped += 1
	kind = {1: "sphere", 2: "bitmap", 3: "point_bitmap"}.get(
	primitive_type, "unknown")
	lines.append(f"# skipped non-OBJ primitive: {kind}")
	continue

	polygon_count = u16(data, at + 1)
	polygon_offset = u16(data, at + 3)
	checked_range(data, polygon_offset, polygon_count * 8,
	f"variant 0x{at:x} polygon list")
	lines.append(
	f"# polygon_count={polygon_count} polygon_offset=0x{polygon_offset:04x}")
	for polygon_index in range(polygon_count):
	p = polygon_offset + polygon_index * 8
	flags = data[p]
	selectors_offset = u16(data, p + 6)
	selectors = selector_stream(data, selectors_offset)
	if len(selectors) < 2:
	skipped += 1
	continue
	indices = [vertex(part, selector) for selector in selectors]
	lines.append(
	f"# polygon={polygon_index} record=0x{p:04x} "
	f"flags=0x{flags:02x} selectors=" +
	" ".join(f"0x{x:02x}" for x in selectors))
	if len(indices) == 2:
	lines.append("l " + " ".join(map(str, indices)))
	line_count += 1
	else:
	lines.append("f " + " ".join(map(str, indices)))
	face_count += 1

	out.parent.mkdir(parents=True, exist_ok=True)
	out.write_text("\n".join(lines) + "\n")
	return len(details), vertex_count, face_count, line_count, skipped


	def main() -> int:
	ap = argparse.ArgumentParser()
	ap.add_argument("tbl", type=Path)
	ap.add_argument("-o", "--out", type=Path, required=True)
	ap.add_argument("--scale", type=float, default=1.0 / 256.0,
	help="scale raw XYZ values for OBJ (default: 1/256)")
	args = ap.parse_args()
	try:
	details, vertices, faces, lines, skipped = export(
	args.tbl, args.out, args.scale)
	except (OSError, ValueError, struct.error) as exc:
	ap.error(str(exc))
	print(f"{args.tbl.name}: details={details} vertices={vertices} "
	f"faces={faces} lines={lines} skipped={skipped} -> {args.out}")
	return 0


	if __name__ == "__main__":
	raise SystemExit(main())
	#!/usr/bin/env python3
	"""Self-contained Mac Red Baron package-to-OBJ diagnostic exporter.

	This file intentionally imports no project modules. It contains the small
	amount of TBL/DAT/CLG parsing needed by the package exporter, including the
	detail/part/frame/draw names, filters, and metadata report.
	"""
	from __future__ import annotations

	import argparse
	import struct
	from pathlib import Path

	RAW_TYPES = {0x80, 0x81, 0xA0, 0xA1}


	def be16(data, off):
	return int.from_bytes(data[off:off + 2], "big")


	def tbl_dat(path):
	raw = Path(path).read_bytes()
	q = 0
	while q + 8 <= len(raw):
	tag = raw[q:q + 4]
	size = int.from_bytes(raw[q + 4:q + 7], "little")
	end = q + 8 + size
	if end > len(raw):
	raise ValueError("truncated TBL chunk")
	if tag == b"DAT:":
	return raw[q + 8:end]
	q = end
	raise ValueError("TBL has no DAT chunk")


	def validate_clg(path):
	"""Validate the matching six-group CLG framing and byte order."""
	raw = Path(path).read_bytes()
	if len(raw) < 12:
	raise ValueError("CLG is shorter than its six group counts")
	counts = struct.unpack_from(">6H", raw, 0)
	expected = 12 + 2 * sum(counts)
	if len(raw) != expected:
	raise ValueError("CLG size does not match its six big-endian counts")


	def raw_record(data, off):
	if off < 0 or off + 8 > len(data) or data[off] not in RAW_TYPES:
	return None
	return {"offset": off, "type": data[off],
	"bytes": data[off:off + 8].hex(" "),
	"link": be16(data, off + 6)}


	def streams(data, records):
	out = []
	seen = set()
	for rec in records:
	start = rec["link"] + 8
	if not 0 <= start < len(data):
	continue
	end = data.find(b"\xff", start)
	if end < 0 or (start, end) in seen:
	continue
	seen.add((start, end))
	out.append({"source_record": rec["offset"],
	"record_type": "0x%02x" % rec["type"],
	"offset": start, "values": list(data[start:end]),
	"terminator_offset": end})
	return out


	def is_group(data, off):
	return 0 <= off and off + 8 <= len(data) and data[off:off + 3] == b"\0\0\0"


	def raw_group(data, off):
	"""Read the observed group-header/linked-record forms."""
	if not is_group(data, off):
	return None
	count = be16(data, off + 2)
	anchor = be16(data, off + 4)
	if anchor != off and (is_group(data, anchor) or
	raw_record(data, anchor) is not None):
	child = anchor
	else:
	child = off + 8

	# Most groups are a contiguous record chain. Some encode one initial
	# record plus count more records, so try that form first.
	for amount, layout in ((count + 1, "initial_plus_count_contiguous"),
	(count, "contiguous")):
	if amount <= 0:
	continue
	recs = [raw_record(data, child + i * 8) for i in range(amount)]
	if all(recs):
	return {"count": count, "anchor": anchor, "child": child,
	"records": recs, "record_layout": layout,
	"streams": streams(data, recs)}

	# Another observed form has one record whose link points back to itself,
	# followed by a terminated inline stream and then the remaining records.
	first = raw_record(data, child)
	if count and first is not None and first["link"] == child:
	end = data.find(b"\xff", child + 8)
	after = len(data) if end < 0 else end + 1
	if after < len(data) and data[after] == 0:
	after += 1
	trailing = [raw_record(data, after + i * 8) for i in range(count)]
	if end >= 0 and all(trailing):
	recs = [first] + trailing
	return {"count": count, "anchor": anchor, "child": child,
	"records": recs,
	"record_layout": "initial_inline_plus_count_contiguous",
	"streams": streams(data, recs)}

	# Otherwise follow links. Stop when the declared count is reached.
	recs = []
	q = child
	seen = set()
	for _ in range(count + 1):
	if q in seen:
	break
	seen.add(q)
	rec = raw_record(data, q)
	if rec is None:
	break
	recs.append(rec)
	nxt = rec["link"]
	if len(recs) >= count:
	break
	if nxt == q:
	end = data.find(b"\xff", q + 8)
	q = len(data) if end < 0 else end + 1
	if q < len(data) and data[q] == 0:
	q += 1
	else:
	q = nxt
	if not recs:
	return None
	return {"count": count, "anchor": anchor, "child": child,
	"records": recs, "record_layout": "linked_or_inline",
	"streams": streams(data, recs)}


	def group_for_target(data, target):
	"""Resolve a draw target using declared offsets only.

	There is deliberately no nearby-byte search here. The executable-style
	walk uses the known target, the fixed +8 envelope, the group anchor, the
	declared count, and each record's link.
	"""
	group = raw_group(data, target + 8)
	if group is not None:
	return group
	return None


	def frame_streams(data, entry, root, frame, include_auxiliary):
	"""Read one executable-selected per-part frame from the loaded DAT."""
	period = entry["cell_period"]
	draw_base = root + entry["draw_target"]
	if frame < 0 or frame >= period or draw_base + frame * 8 + 8 > len(data):
	return None, []
	draw_off = draw_base + frame * 8
	if data[draw_off] != 0:
	return draw_off, []
	count = be16(data, draw_off + 2)
	command_base = root + be16(data, draw_off + 4)
	result = []
	for command_number in range(count):
	command_off = command_base + command_number * 8
	if command_off + 8 > len(data):
	break
	command_type = data[command_off]
	start = root + be16(data, command_off + 6)
	if not 0 <= start < len(data):
	continue
	end = data.find(b"\xff", start)
	if end < 0 or (not include_auxiliary and command_type not in (0xa0, 0xa1)):
	continue
	result.append({"frame": frame, "draw_offset": draw_off,
	"command_number": command_number,
	"source_record": command_off,
	"record_type": "0x%02x" % command_type,
	"offset": start, "values": list(data[start:end])})
	return draw_off, result


	def package_entries(data):
	"""Read the repeated root directory and its 14-byte entries."""
	if len(data) < 16 or int.from_bytes(data[0:4], "big") != 8:
	raise ValueError("DAT does not begin with the expected root pointer")
	root = 8
	entries_by_detail = []
	detail_count = be16(data, root + 8)
	detail_offset = be16(data, root + 0xa)
	q = root + detail_offset
	descriptors = []
	for _ in range(detail_count):
	if q + 6 > len(data):
	break
	kind = be16(data, q)
	count = be16(data, q + 2)
	descriptors.append((kind, count, root + be16(data, q + 4)))
	q += 6

	for kind, count, target in descriptors:
	if target < 0 or target + count * 14 > len(data):
	continue
	entries = []
	for index in range(count):
	off = target + index * 14
	words = [be16(data, off + i) for i in range(0, 14, 2)]
	entries.append({"index": index, "offset": off,
	"state_channel": data[off],
	"point_target": words[2],
	"cell_period": words[3],
	"draw_target": words[4]})
	entries_by_detail.append({"raw_key": kind, "entries": entries})
	return entries_by_detail


	def point_values(data, base, selectors):
	if not selectors or base < 0:
	return None
	end = base + 6 * max(selectors) + 6
	if end > len(data):
	return None
	return [struct.unpack_from(">hhh", data, base + 6 * value)
	for value in selectors]


	def selected_streams(data, entry, include_aux):
	group = group_for_target(data, entry["draw_target"])
	if group is None:
	return None, []
	result = streams(data, group["records"])
	if not include_aux:
	result = [s for s in result if s["record_type"] in ("0xa0", "0xa1")]
	return group, result


	def metadata(data, sections, include_aux):
	lines = ["Model metadata", "===============",
	"detail levels: %d" % len(sections)]
	for detail, section in enumerate(sections):
	lines.append("detail %d (raw key 0x%02x): %d parts" %
	(detail, section["raw_key"], len(section["entries"])))
	for part, entry in enumerate(section["entries"]):
	lines.append(" part %d: %d frames, channel=%d, point=0x%04x frame_table=0x%04x" %
	(part, entry["cell_period"], entry["state_channel"],
	entry["point_target"], entry["draw_target"]))
	for frame in range(entry["cell_period"]):
	draw_off, frame_items = frame_streams(data, entry, 8, frame,
	include_aux)
	lines.append(" frame %d: draw=0x%04x commands=%d" %
	(frame, draw_off or 0, len(frame_items)))
	for draw, stream in enumerate(frame_items):
	lines.append(" draw %d: type=%s selectors=%d source=0x%04x stream=0x%04x" %
	(draw, stream["record_type"], len(stream["values"]),
	stream["source_record"], stream["offset"]))
	return lines


	def main():
	ap = argparse.ArgumentParser()
	ap.add_argument("tbl", type=Path)
	ap.add_argument("--clg", type=Path,
	help="matching CLG; accepted for validating the pair")
	ap.add_argument("-o", "--out", type=Path)
	ap.add_argument("--scale", type=float, default=256.0)
	ap.add_argument("--point-header", type=int, default=8)
	ap.add_argument("--include-auxiliary", action="store_true")
	ap.add_argument("--section-key", type=lambda value: int(value, 0))
	ap.add_argument("--detail-level", "--detail", type=int)
	ap.add_argument("--part-number", "--part", type=int)
	ap.add_argument("--subpart-number", "--subpart", "--draw-record",
	dest="subpart_number", type=int,
	help="export only this zero-based draw command within each frame")
	ap.add_argument("--frame-number", "--frame", type=int,
	help="export only this zero-based per-part frame")
	ap.add_argument("--metadata", action="store_true")
	args = ap.parse_args()

	clg = args.clg or args.tbl.with_suffix(".CLG")
	if not clg.exists():
	raise ValueError("CLG file does not exist: %s" % clg)
	validate_clg(clg)
	data = tbl_dat(args.tbl)
	sections = package_entries(data)
	if args.metadata:
	print("\n".join(metadata(data, sections, args.include_auxiliary)))
	print()

	lines = ["# Red Baron Mac package export",
	"# coordinates: signed big-endian i16 XYZ, runtime scale / %g" % args.scale,
	"# object name: detail_<level>_part_<number>_frame_<number>",
	"# frame is a selectable per-part visual state; its draw commands follow"]
	vcount = fcount = lcount = ocount = skipped = 0
	for detail, section in enumerate(sections):
	if args.detail_level is not None and detail != args.detail_level:
	continue
	if args.section_key is not None and section["raw_key"] != args.section_key:
	continue
	for part, entry in enumerate(section["entries"]):
	if args.part_number is not None and part != args.part_number:
	continue
	base = entry["point_target"] + args.point_header
	for frame in range(entry["cell_period"]):
	if args.frame_number is not None and frame != args.frame_number:
	continue
	draw_off, frame_items = frame_streams(
	data, entry, 8, frame, args.include_auxiliary)
	if draw_off is None:
	skipped += 1
	continue
	geometry = []
	for draw, stream in enumerate(frame_items):
	if args.subpart_number is not None and draw != args.subpart_number:
	continue
	values = tuple(stream["values"])
	if len(values) < (2 if args.include_auxiliary else 3):
	continue
	xyz = point_values(data, base, values)
	if xyz is None:
	skipped += 1
	continue
	geometry.append((draw, stream, xyz, values))
	if not geometry:
	continue
	name = "detail_%02d_part_%03d_frame_%03d" % (
	detail, part, frame)
	lines.append("o " + name)
	lines.append("# detail=%d raw_section_key=0x%02x part=%d frame=%d draw_commands=%d point_base=0x%04x" %
	(detail, section["raw_key"], part, frame,
	len(geometry), base))
	for draw, stream, xyz, values in geometry:
	lines.append("# draw=%d record_type=%s record=0x%04x stream=0x%04x selectors=%s" %
	(draw, stream["record_type"], stream["source_record"],
	stream["offset"], ",".join("%02x" % value for value in values)))
	for x, y, z in xyz:
	lines.append("v %.6f %.6f %.6f" %
	(x / args.scale, y / args.scale, z / args.scale))
	first = vcount + 1
	indices = [str(first + i) for i in range(len(xyz))]
	if len(indices) == 2:
	lines.append("l " + " ".join(indices))
	lcount += 1
	else:
	lines.append("f " + " ".join(indices))
	fcount += 1
	vcount += len(xyz)
	ocount += 1

	out = args.out or args.tbl.with_suffix(".package.obj")
	out.write_text("\n".join(lines) + "\n")
	print("wrote %s" % out)
	print("objects=%d faces=%d lines=%d vertices=%d skipped=%d" %
	(ocount, fcount, lcount, vcount, skipped))


	if __name__ == "__main__":
	main()