#!/usr/bin/env python3 """Lossless, bounded reader for the supplied Neutron GAM entity files. No original file is modified. Unknown property types stay opaque. The four bytes after each object are retained without assigning an unverified interpretation. """ from __future__ import annotations import argparse import json import math import struct from dataclasses import asdict, dataclass from pathlib import Path class FormatError(ValueError): pass class Reader: def __init__(self, data: bytes): self.data = data self.offset = 0 def take(self, count: int) -> bytes: if count < 0 or count > len(self.data) - self.offset: raise FormatError(f"truncated data at 0x{self.offset:x}: need {count} bytes") result = self.data[self.offset:self.offset + count] self.offset += count return result def u32(self) -> int: return struct.unpack(">I", self.take(4))[0] def text(self, count: int) -> str: return self.take(count).decode("latin-1") def pascal(self) -> str: return self.text(self.take(1)[0]) @dataclass class Property: name: str type: int length: int value: str | int | float raw: str offset: int @dataclass class Entity: kind: str offset: int properties: list[Property] trailer: str def values(self) -> dict: return {p.name: p.value for p in self.properties} @dataclass class Level: code: str entities: list[Entity] size: int def parse(data: bytes) -> Level: r = Reader(data) code = r.text(4) if not code.isascii() or not code.isalnum(): raise FormatError("invalid level FourCC") count = r.u32() if count > (len(data) - 8) // 12: raise FormatError("object count exceeds file capacity") entities = [] for _ in range(count): offset = r.offset kind, property_count = r.text(4), r.u32() if property_count > (len(data) - r.offset) // 10: raise FormatError(f"property count exceeds capacity at 0x{offset:x}") properties = [] names = set() for _ in range(property_count): property_offset = r.offset name, type_id, length = r.pascal(), r.u32(), r.u32() if name in names: raise FormatError(f"duplicate property {name!r} at 0x{property_offset:x}") names.add(name) if type_id == 1: actual = r.take(1)[0] if actual != length: raise FormatError(f"string size mismatch at 0x{property_offset:x}") raw = r.take(length) if type_id == 1: value = raw.decode("latin-1") elif type_id in (3, 6): if length != 4: raise FormatError(f"scalar size {length} at 0x{property_offset:x}") value = struct.unpack(">f" if type_id == 3 else ">i", raw)[0] if isinstance(value, float) and not math.isfinite(value): raise FormatError(f"non-finite scalar at 0x{property_offset:x}") else: value = raw.hex() properties.append(Property(name, type_id, length, value, raw.hex(), property_offset)) entities.append(Entity(kind, offset, properties, r.take(4).hex())) if r.offset != len(data): raise FormatError(f"{len(data) - r.offset} unexpected trailing bytes at 0x{r.offset:x}") return Level(code, entities, len(data)) def encode(level: Level) -> bytes: """Re-encode parsed data to prove every byte has been accounted for.""" out = bytearray(level.code.encode("latin-1") + struct.pack(">I", len(level.entities))) for e in level.entities: out += e.kind.encode("latin-1") + struct.pack(">I", len(e.properties)) for p in e.properties: name = p.name.encode("latin-1") raw = bytes.fromhex(p.raw) out += bytes([len(name)]) + name + struct.pack(">II", p.type, p.length) if p.type == 1: out += bytes([p.length]) out += raw out += bytes.fromhex(e.trailer) return bytes(out) def main() -> None: cli = argparse.ArgumentParser(description=__doc__) cli.add_argument("input", type=Path) cli.add_argument("--output", type=Path) args = cli.parse_args() raw = args.input.read_bytes() level = parse(raw) if encode(level) != raw: raise FormatError("round trip differs") text = json.dumps(asdict(level), indent=2, ensure_ascii=True, allow_nan=False) + "\n" if args.output: if args.output.resolve() == args.input.resolve(): cli.error("output must differ from original input") args.output.parent.mkdir(parents=True, exist_ok=True) args.output.write_text(text) else: print(text, end="") if __name__ == "__main__": main()