Files
Neutron/tools/binary/checkpoint_script_state.py

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()