145 lines
6.0 KiB
Python
145 lines
6.0 KiB
Python
#!/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("<i", raw, 1)[0]
|
|
|
|
|
|
def collect(root: Path) -> 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("<I", read_va(pe, va, 4))[0]
|
|
vtables.append(dict(name=name, table=hex(table), slot=hex(slot),
|
|
va=hex(va), file_offset=hex(pe.offset(va-pe.base)),
|
|
target=hex(actual), matches=actual == expected))
|
|
route = []
|
|
for filename, tags in (("gam/level1b.gam", {"startexp", "shrinkray", "neutron1a", "labtoneigh"}),
|
|
("gam/VR04.gam", {"phonebooth"})):
|
|
path = find_case(root, filename)
|
|
raw = path.read_bytes()
|
|
level = gam.parse(raw)
|
|
selected = []
|
|
for entity in level.entities:
|
|
fields = entity.values()
|
|
tag = str(fields.get("ObjectTag", ""))
|
|
if tag.casefold() in tags or entity.kind == "LOAD":
|
|
selected.append(dict(kind=entity.kind, file_offset=hex(entity.offset),
|
|
fields=fields))
|
|
route.append(dict(file=filename, sha256=hashlib.sha256(raw).hexdigest(),
|
|
code=level.code, entities=selected))
|
|
return dict(module="Neutron.exe", sha256=digest, known_binary=digest == EXE_SHA256,
|
|
sites=sites, vtables=vtables, route=route,
|
|
scope="Static bytes/data only; no original runtime execution.")
|
|
|
|
|
|
def main() -> 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()
|