#!/usr/bin/env python3 """Build a row-level review of the original EXE opening/title stream.""" from __future__ import annotations import html import json import re import struct from pathlib import Path from typing import Any from probe_exe_scene_tables import offset_to_va, read_sections, va_to_offset from summarize_opening_start_context import ( OPENING_SCRIPT_END, OPENING_SCRIPT_START, RESOURCE_ROWS, build_summary as build_opening_summary, file_hex, hex32, ) ROOT = Path(__file__).resolve().parents[1] OUT = ROOT / "out" EXE = ROOT / "Hwanse2.exe" DESCRIPTOR_POINTERS = { 0x004A3CA4: "btl_k2.cns descriptor pointer candidate", 0x004A3CF8: "logo_00.cns descriptor pointer candidate", 0x004A3D20: "title.cns descriptor pointer candidate", } EXACT_AUDIO_SITES = { 0x004A2DF4: { "category": "audio-midi-candidate", "label": "MLK id 10 candidate", "note": "value 0x0a003026; high byte 0x0a is EXE MIDI track id 10; consumer not promoted", }, 0x004A3060: { "category": "audio-wlk-candidate", "label": "WLK id 35 candidate 1", "note": "value 0x23000124; high byte 0x23 is EXE WLK id 35; first confirmed logo impact sound", }, 0x004A308C: { "category": "audio-wlk-candidate", "label": "WLK id 35 candidate 2", "note": "value 0x23000124; high byte 0x23 is EXE WLK id 35; second confirmed logo impact sound", }, } BLOCK_ANCHORS = [ { "key": "stream-start", "label": "Opening stream start", "va": OPENING_SCRIPT_START, "note": "current selected pointer 8:0; resource cluster immediately precedes this stream", }, { "key": "midi11", "label": "MLK id 10 candidate", "va": 0x004A2DF4, "note": "strong BGM row near middata.mlk pointer evidence", }, { "key": "logo-hit-1", "label": "Logo impact WLK row 1", "va": 0x004A3060, "note": "first of two WLK id 35 logo sounds", }, { "key": "logo-hit-2", "label": "Logo impact WLK row 2", "va": 0x004A308C, "note": "second of two WLK id 35 logo sounds", }, { "key": "btl-k2-descriptor", "label": "btl_k2 descriptor area", "va": 0x004A3CA4, "note": "battle background descriptor pointer candidate area", }, { "key": "logo-descriptor", "label": "logo_00 descriptor area", "va": 0x004A3CF8, "note": "split logo descriptor pointer candidate area", }, { "key": "title-descriptor", "label": "title descriptor area", "va": 0x004A3D20, "note": "final title screen descriptor pointer candidate area", }, ] def load_json(path: Path, fallback: Any) -> Any: if not path.exists(): return fallback try: return json.loads(path.read_text(encoding="utf-8")) except (OSError, json.JSONDecodeError): return fallback def c_string(exe: bytes, offset: int) -> str: end = exe.find(b"\0", offset) if end < 0: end = len(exe) return exe[offset:end].decode("ascii", "replace") def find_resource_strings(exe: bytes, sections: list[dict]) -> dict[int, str]: strings: dict[int, str] = {} for match in re.finditer(rb"[a-z0-9_]{2,20}\.(?:cns|mlk|wlk)\0", exe): va = offset_to_va(sections, match.start()) if va is not None: strings[va] = c_string(exe, match.start()) return strings def load_handler_map() -> dict[int, dict[str, Any]]: table = load_json(OUT / "script_handler_table.json", {}) result: dict[int, dict[str, Any]] = {} for row in table.get("entries") or []: opcode = row.get("opcode") if isinstance(opcode, int): result[opcode] = row return result def classify_pointer(value: int, sections: list[dict], resource_strings: dict[int, str]) -> tuple[str, list[str]]: notes: list[str] = [] category = "" if value in resource_strings: category = "resource-pointer" notes.append(f"points to resource string `{resource_strings[value]}`") elif value in DESCRIPTOR_POINTERS: category = "descriptor-pointer" notes.append(DESCRIPTOR_POINTERS[value]) elif OPENING_SCRIPT_START <= value < OPENING_SCRIPT_END: category = "local-pointer" notes.append("points inside opening selected-pointer range") elif va_to_offset(sections, value) is not None and 0x00400000 <= value < 0x00600000: category = "exe-pointer" notes.append("points inside mapped EXE image") return category, notes def summarize_handler(low: int, handler_map: dict[int, dict[str, Any]]) -> str: row = handler_map.get(low) if not row: return "-" default = "default" if row.get("isDefaultHandler") else "handler" return f"{row.get('handlerVaHex', '-')} ({default})" def annotate_row( exe: bytes, sections: list[dict], resource_strings: dict[int, str], handler_map: dict[int, dict[str, Any]], off: int, index: int, ) -> dict[str, Any]: value = struct.unpack_from("> 8) & 0xFF b2 = (value >> 16) & 0xFF b3 = (value >> 24) & 0xFF categories: list[str] = [] notes: list[str] = [] status = "raw" label = "" exact = EXACT_AUDIO_SITES.get(va) if exact: categories.append(exact["category"]) notes.append(exact["note"]) status = "strong-candidate-unpromoted" label = exact["label"] pointer_category, pointer_notes = classify_pointer(value, sections, resource_strings) if pointer_category: categories.append(pointer_category) notes.extend(pointer_notes) if status == "raw": status = "pointer-evidence" if b0 in {0x24, 0x26, 0x36, 0x38, 0x3B, 0x44, 0x45, 0x46, 0x52, 0x53, 0x58, 0x60, 0x61, 0x62, 0x63}: categories.append("opcode-like-low-byte") notes.append("low byte matches a known or interesting script-handler index; this can still be operand/pointer collision") if status == "raw": status = "opcode-like" if value <= 0xFF: categories.append("small-scalar") elif value <= 0xFFFF: categories.append("word-scalar") elif not categories: categories.append("packed-or-scalar") if not label and notes: label = notes[0] return { "index": index, "va": va, "vaHex": hex32(va), "fileOffset": off, "fileOffsetHex": file_hex(off), "value": value, "valueHex": hex32(value), "bytesHex": [f"0x{b:02x}" for b in (b0, b1, b2, b3)], "lowByteHex": f"0x{b0:02x}", "byte1Hex": f"0x{b1:02x}", "byte2Hex": f"0x{b2:02x}", "byte3Hex": f"0x{b3:02x}", "handlerCandidate": summarize_handler(b0, handler_map), "categories": sorted(set(categories)), "primaryCategory": categories[0] if categories else "raw", "status": status, "label": label, "notes": notes, } def collect_action_payload_direct_hits(opening_summary: dict[str, Any]) -> list[dict[str, Any]]: probe = opening_summary.get("decodeProbe") or {} battle = (probe.get("battleActionPayloadProbe") or {}) hits = battle.get("checkedPointerHits") or {} rows = [] for label, item in sorted(hits.items()): rows.append( { "label": label, "targetVaHex": item.get("targetVaHex"), "openingHitCount": item.get("openingHitCount", 0), "status": "not-directly-referenced" if item.get("openingHitCount", 0) == 0 else "direct-reference-found", } ) return rows def build_focus_windows(rows: list[dict[str, Any]], radius: int = 8) -> list[dict[str, Any]]: by_va = {row["va"]: row for row in rows} result = [] for anchor in BLOCK_ANCHORS: va = anchor["va"] start = va - radius * 4 end = va + radius * 4 window_rows = [row for row in rows if start <= row["va"] <= end] result.append( { **anchor, "vaHex": hex32(va), "present": va in by_va, "rows": window_rows, } ) return result def build_summary() -> dict[str, Any]: opening_summary = build_opening_summary() if not EXE.exists(): return { "available": False, "reason": "Hwanse2.exe not found", "openingSummary": opening_summary, } exe = EXE.read_bytes() sections = read_sections(exe) start = va_to_offset(sections, OPENING_SCRIPT_START) end = va_to_offset(sections, OPENING_SCRIPT_END) if start is None or end is None: return { "available": False, "reason": "opening range is not mapped in PE sections", "openingSummary": opening_summary, } resource_strings = find_resource_strings(exe, sections) handler_map = load_handler_map() rows = [ annotate_row(exe, sections, resource_strings, handler_map, off, index) for index, off in enumerate(range(start, end, 4)) ] low_counts: dict[str, int] = {} category_counts: dict[str, int] = {} status_counts: dict[str, int] = {} for row in rows: low_counts[row["lowByteHex"]] = low_counts.get(row["lowByteHex"], 0) + 1 status_counts[row["status"]] = status_counts.get(row["status"], 0) + 1 for category in row["categories"]: category_counts[category] = category_counts.get(category, 0) + 1 interesting_rows = [ row for row in rows if row["status"] != "raw" or any(category in row["categories"] for category in ("resource-pointer", "descriptor-pointer", "local-pointer")) ] return { "available": True, "objective": "row-level opening/title selected-pointer stream review", "rangeVaHex": f"{hex32(OPENING_SCRIPT_START)}..{hex32(OPENING_SCRIPT_END)}", "rangeFileOffsetHex": f"{file_hex(start)}..{file_hex(end)}", "rowCount": len(rows), "classification": "review-table-candidate-not-execution-proof", "dataModelCaution": ( "This range is mixed descriptor/script data. Rows are dword-aligned review units; " "low-byte handler labels are candidates only until a consumer path is decoded." ), "openingStartContextHref": "opening_start_context.md", "resourceRows": RESOURCE_ROWS, "observedOpeningSequence": opening_summary.get("observedOpeningSequence", []), "promotedConclusions": [ "0x004a2d38 remains the current opening/title selected-pointer candidate.", "The page promotes resource adjacency and observed sequence alignment, not exact opcode execution.", "MLK id 10 and the two WLK id 35 rows are strong candidates, still unpromoted as decoded audio calls.", "The opening does not directly contain the grounded 신기 skill payload VAs; action selection is still indirect.", ], "strongCandidates": [ { "kind": "MIDI/BGM", "siteVaHex": "0x004a2df4", "fileOffsetHex": "0x0a0df4", "valueHex": "0x0a003026", "candidateMeaning": "MLK id 10 if high byte is EXE track id 10", "promotion": "unpromoted", }, { "kind": "WLK/SFX", "siteVaHex": "0x004a3060", "fileOffsetHex": "0x0a1060", "valueHex": "0x23000124", "candidateMeaning": "first WLK id 35 split-logo impact", "promotion": "unpromoted", }, { "kind": "WLK/SFX", "siteVaHex": "0x004a308c", "fileOffsetHex": "0x0a108c", "valueHex": "0x23000124", "candidateMeaning": "second WLK id 35 split-logo impact", "promotion": "unpromoted", }, ], "actionPayloadDirectHits": collect_action_payload_direct_hits(opening_summary), "counts": { "lowByteTop20": [ {"lowByteHex": key, "count": value} for key, value in sorted(low_counts.items(), key=lambda item: (-item[1], item[0]))[:20] ], "categoryCounts": [ {"category": key, "count": value} for key, value in sorted(category_counts.items(), key=lambda item: (-item[1], item[0])) ], "statusCounts": [ {"status": key, "count": value} for key, value in sorted(status_counts.items(), key=lambda item: (-item[1], item[0])) ], }, "focusWindows": build_focus_windows(rows), "interestingRows": interesting_rows, "streamRows": rows, "nextProofNeeded": [ "Trace the consumer of the two 0x23000124 rows to prove or reject WLK id 35 playback.", "Trace the 0x0a003026 row and adjacent middata.mlk pointer to prove or reject MLK id 10 playback.", "Find the indirect actor/action selector that maps the opening actions to 맹호스페셜/선렬각/쾌진격 신기 payloads.", ], } def render_status_chips(rows: list[dict[str, Any]], key: str, label_key: str) -> str: chips = [] for row in rows: chips.append( f"{html.escape(str(row[label_key]))} {html.escape(str(row['count']))}" ) return "".join(chips) def row_tr(row: dict[str, Any]) -> str: notes = "
".join(html.escape(note) for note in row.get("notes") or []) categories = " ".join(row.get("categories") or []) class_name = " ".join(f"cat-{category}" for category in row.get("categories") or []) return ( f"" f"{row['index']}" f"{html.escape(row['vaHex'])}
{html.escape(row['fileOffsetHex'])}" f"{html.escape(row['valueHex'])}" f"{html.escape(' '.join(row['bytesHex']))}" f"{html.escape(row['lowByteHex'])}
{html.escape(row['handlerCandidate'])}" f"{html.escape(row['status'])}
{html.escape(categories)}" f"{notes}" "" ) def focus_window_html(windows: list[dict[str, Any]]) -> str: sections = [] for window in windows: rows = "".join(row_tr(row) for row in window["rows"]) sections.append( "
" f"{html.escape(window['label'])} · {html.escape(window['vaHex'])}" f"

{html.escape(window['note'])}

" "
" f"{rows}" "
#VA/filevaluebyteslow/handlerstatus/categorynotes
" "
" ) return "".join(sections) def html_page(summary: dict[str, Any]) -> str: if not summary.get("available"): reason = html.escape(summary.get("reason", "unavailable")) return f"Opening Opcode Review

{reason}

" conclusions = "".join(f"
  • {html.escape(item)}
    • " for item in summary["promotedConclusions"]) strong_rows = "".join( "" f"{html.escape(row['kind'])}" f"{html.escape(row['siteVaHex'])}
    {html.escape(row['fileOffsetHex'])}" f"{html.escape(row['valueHex'])}" f"{html.escape(row['candidateMeaning'])}" f"{html.escape(row['promotion'])}" "" for row in summary["strongCandidates"] ) action_rows = "".join( "" f"{html.escape(row['label'])}" f"{html.escape(str(row.get('targetVaHex') or '-'))}" f"{html.escape(str(row.get('openingHitCount', 0)))}" f"{html.escape(row['status'])}" "" for row in summary["actionPayloadDirectHits"] ) low_chips = render_status_chips(summary["counts"]["lowByteTop20"], "lowByteHex", "lowByteHex") category_chips = render_status_chips(summary["counts"]["categoryCounts"], "category", "category") status_chips = render_status_chips(summary["counts"]["statusCounts"], "status", "status") interesting_rows = "".join(row_tr(row) for row in summary["interestingRows"]) stream_rows = "".join(row_tr(row) for row in summary["streamRows"]) proof_items = "".join(f"
  • {html.escape(item)}
    • " for item in summary["nextProofNeeded"]) return "\n".join( [ "", "", "", "Opening Opcode Review", "", "", "
    ", "
    ", "

    Opening Opcode Review

    ", f"

    range {html.escape(summary['rangeVaHex'])} / file {html.escape(summary['rangeFileOffsetHex'])} · {summary['rowCount']} dword rows · opening summary

    ", "
    ", "

    Boundary

    candidate review, not execution proof
    ", f"

    {html.escape(summary['dataModelCaution'])}

    ", f"
      {conclusions}
    ", f"

    status counts {status_chips}

    ", f"

    category counts {category_chips}

    ", f"

    low byte top20 {low_chips}

    ", "
    ", "

    Strong Candidate Rows

    still unpromoted
    ", strong_rows, "
    kindsitevaluecandidate meaningpromotion
    ", "

    Action Payload Direct Reference Probe

    expected: 0 direct hits
    ", action_rows, "
    targetVAopening direct hitsstatus
    ", "

    Focus Windows

    ", focus_window_html(summary["focusWindows"]), "
    ", "

    Interesting Rows

    audio/resource/local/opcode-like rows
    ", interesting_rows, "
    #VA/filevaluebyteslow/handlerstatus/categorynotes
    ", "

    Full Dword Stream

    ", stream_rows, "
    #VA/filevaluebyteslow/handlerstatus/categorynotes
    ", "

    Next Proof Needed

      ", proof_items, "
    ", "", "
    ", ] ) def write_outputs(summary: dict[str, Any]) -> None: OUT.mkdir(parents=True, exist_ok=True) (OUT / "opening_opcode_review.json").write_text( json.dumps(summary, ensure_ascii=False, separators=(",", ":")) + "\n", encoding="utf-8", ) (OUT / "opening_opcode_review.html").write_text(html_page(summary), encoding="utf-8") def main() -> None: summary = build_summary() write_outputs(summary) print(f"wrote opening opcode review -> {OUT / 'opening_opcode_review.html'}") if __name__ == "__main__": main()