Record original inventory and recover all GAM level entities

This commit is contained in:
UnixNight committed 2026-10-23 17:08:18 -04:00
commit d62e2ab4de
16 files changed
+3954

No files matched your search

+151
View File
@@ -0,0 +1,151 @@
#!/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()
+32
View File
@@ -0,0 +1,32 @@
#!/usr/bin/env python3
"""Inventory or verify originals with SHA-256; never writes to the source tree."""
import argparse
import hashlib
import json
from pathlib import Path
def inventory(root):
return [{"path": p.relative_to(root).as_posix(), "size": p.stat().st_size,
"sha256": hashlib.sha256(p.read_bytes()).hexdigest(),
"header": p.read_bytes()[:16].hex()}
for p in sorted(root.rglob("*")) if p.is_file()]
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("root", type=Path)
parser.add_argument("--verify", type=Path)
args = parser.parse_args()
files = inventory(args.root)
if args.verify:
previous = json.loads(args.verify.read_text())["files"]
if files != previous:
raise SystemExit("Original inventory differs from recorded baseline")
print(f"Verified {len(files)} unchanged original files")
else:
print(json.dumps({"root": str(args.root), "files": files}, indent=2))
if __name__ == "__main__":
main()