#!/usr/bin/env python3 """Read-only script/task/RETURN checkpoint evidence from the supplied originals. Reports preferred-base VAs, PE-mapped file offsets, exact bytes and dependencies. No original code is executed. Assertions establish the inspected binary identity and call/field provenance, not original-game runtime behavior. """ from __future__ import annotations import argparse import hashlib import json from pathlib import Path import struct import sys sys.path.insert(0, str(Path(__file__).resolve().parent)) sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "levels")) from pe_inspect import PE import gam EXE_SHA256 = "f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8" # Small decisive sites, independently checked against objdump. Offsets are never # assumed to equal RVA: PE.offset performs the actual section mapping. SITES = ( ("task_objective_before_records", 0x45FB5B, "e8f073faff"), ("task_record_mutation", 0x45FB7F, "895f64"), ("task_entity_callback", 0x45FBD9, "ff9024040000"), ("carl_query_scene", 0x413F3D, "e85ebf0400"), ("carl_generic_callback", 0x413F4E, "e8eda3ffff"), ("carl_lab_derived_branch", 0x414068, "85db0f8c9800000083fb3c"), ("carl_marker_state", 0x4140AA, "6a06ff9024010000"), ("carl_marker_root", 0x4140E0, "ff9214030000"), ("pickup_checkpoint_level", 0x42AF1B, "898e481e0000"), ("pickup_checkpoint_root", 0x42AF30, "81c6381e0000"), ("stage_preserve_test", 0x43B78E, "8a83a509000084c07537"), ("stage_root_write", 0x43B7B1, "8d8ba8090000"), ("stage_game_load_request", 0x43B7F1, "ff9200010000"), ("return_suppress_start", 0x458014, "889054090000"), ("return_preserve_root", 0x458028, "8890a5090000"), ("return_stage_dispatch", 0x45815C, "ff9268010000"), ("scene_postload_dispatch", 0x46E61A, "ff920c040000"), ("jimmy_postload_return_root", 0x423ABF, "ff926c010000"), ("jimmy_postload_control", 0x423B3D, "ff9218010000"), ("tsk_setter_call", 0x460CE2, "e8a9ecffff"), ("tsk_second_matching_callback", 0x460D2E, "ff9024040000"), ("tsk_all_entity_420", 0x460D87, "ff9220040000"), ("load_request_pending", 0x460E7B, "c6057cc64f0001"), ("load_update_reader", 0x460EF0, "e8fbf4ffff"), ("load_update_clear_pending", 0x460EF8, "c6057cc64f0000"), ) VTABLES = ( ("Jimmy complete transition", 0x4A3BDC, 0x168, 0x43B5A0), ("Jimmy complete pickup capture", 0x4A3BDC, 0x1E8, 0x42AF00), ("Jimmy complete capture/effect", 0x4A3BDC, 0x1EC, 0x42AF50), ("Carl game task callback", 0x495364, 0x424, 0x413F30), ("Carl game post-task hook", 0x495364, 0x420, 0x413EB0), ("Jimmy game post-task hook", 0x4A373C, 0x420, 0x472970), ("Jimmy game placement PostLoad", 0x4A373C, 0x40C, 0x423610), ("LOAD game task callback", 0x4D025C, 0x424, 0x458880), ) def find_case(root: Path, relative: str) -> Path: current = root for component in Path(relative).parts: matches = [p for p in current.iterdir() if p.name.casefold() == component.casefold()] if len(matches) != 1: raise ValueError(f"missing or ambiguous original path: {relative}") current = matches[0] return current def read_va(pe: PE, va: int, size: int) -> bytes: if size < 0: raise ValueError("negative byte count") start = pe.offset(va - pe.base) if size and pe.offset(va + size - 1 - pe.base) != start + size - 1: raise ValueError("VA range is not contiguous file data") result = pe.data[start:start + size] if len(result) != size: raise ValueError("truncated VA range") return result def rel_call_target(pe: PE, va: int) -> int: raw = read_va(pe, va, 5) if raw[0] != 0xE8: raise ValueError(f"not a direct relative call at {va:#x}") return va + 5 + struct.unpack_from(" dict: pe = PE(find_case(root, "Neutron.exe")) digest = hashlib.sha256(pe.data).hexdigest() sites = [] for name, va, expected in SITES: actual = read_va(pe, va, len(bytes.fromhex(expected))).hex() site = dict(name=name, va=hex(va), file_offset=hex(pe.offset(va-pe.base)), expected=expected, actual=actual, matches=actual == expected) if actual.startswith("e8"): site["direct_call_target"] = hex(rel_call_target(pe, va)) sites.append(site) vtables = [] for name, table, slot, expected in VTABLES: va = table + slot actual = struct.unpack(" None: cli = argparse.ArgumentParser(description=__doc__) cli.add_argument("original", type=Path) args = cli.parse_args() result = collect(args.original) print(json.dumps(result, indent=2, allow_nan=False)) if not result["known_binary"] or not all(s["matches"] for s in result["sites"] + result["vtables"]): raise SystemExit(1) if __name__ == "__main__": main()