Document architecture checkpoint and restore original task callback order
This commit is contained in:
1 parent
69d0187a21
commit
531883aaac
45 files changed
+2935
-43
No files matched your search
@@ -0,0 +1,144 @@
|
||||
#!/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()
|
||||
Reference in new issue
Block a user