#!/usr/bin/env python3 """Review the remaining RNG selector handler behind field encounter analysis. The shared RNG call at 0x0040bdcc sits inside handler 0x0040bcc9, reached from handler table 0x00440720 opcode 0x1c. This report checks whether the EXE contains well-formed command streams for that opcode and whether any of them can be tied to field walking encounter data. """ from __future__ import annotations import html import json import struct import sys from collections import Counter from pathlib import Path from typing import Any ROOT = Path(__file__).resolve().parents[1] OUT = ROOT / "out" WEB = ROOT / "web" EXE = ROOT / "Hwanse2.exe" sys.path.insert(0, str(ROOT / "tools")) from probe_exe_scene_tables import offset_to_va, read_sections, va_to_offset # noqa: E402 HANDLER_TABLE_VA = 0x00440720 OPCODE = 0x1C HANDLER_ENTRY_VA = HANDLER_TABLE_VA + OPCODE * 4 HANDLER_VA = 0x0040BCC9 RNG_CALL_VA = 0x0040BDCC ACTIVE_COUNT_GLOBAL = 0x004576E8 ACTIVE_ORDER_GLOBAL = 0x004576E9 ACTIVE_SLOT_WEIGHT_BASE = 0x00457756 def h(value: Any) -> str: return html.escape("" if value is None else str(value), quote=True) def hex32(value: int | None) -> str | None: return None if value is None else f"0x{value:08x}" def read_json(path: Path, default: Any) -> Any: try: return json.loads(path.read_text(encoding="utf-8")) except FileNotFoundError: return default def write_json(path: Path, payload: Any) -> None: path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") def va_section(sections: list[dict[str, Any]], va: int) -> dict[str, Any] | None: for section in sections: if section["va"] <= va < section["va"] + section["raw_size"]: return section return None def valid_stream_pointer(sections: list[dict[str, Any]], value: int) -> bool: section = va_section(sections, value) return section is not None and section["name"] in {".text", ".rdata", ".data"} def bytes_at_va(exe: bytes, sections: list[dict[str, Any]], va: int, size: int) -> bytes: offset = va_to_offset(sections, va) if offset is None: return b"" return exe[offset : offset + size] def dword_at_va(exe: bytes, sections: list[dict[str, Any]], va: int) -> int | None: data = bytes_at_va(exe, sections, va, 4) if len(data) != 4: return None return struct.unpack_from(" int: if mode in {0, 2}: return byte2 if mode == 1: return byte3 - byte2 return -1 def scan_well_formed_opcode_blocks(exe: bytes, sections: list[dict[str, Any]]) -> list[dict[str, Any]]: """Find byte streams that the opcode 0x1c handler can plausibly consume. Layout inferred from handler 0x0040bcc9: byte0 opcode 0x1c byte1 mode 0/1/2 byte2 count/range lower byte byte3 upper byte used by mode 1 byte4... dword command pointers """ rows: list[dict[str, Any]] = [] for section in sections: start = section["raw"] end = start + section["raw_size"] for offset in range(start, max(start, end - 12)): if exe[offset] != OPCODE: continue mode = exe[offset + 1] if mode not in {0, 1, 2}: continue byte2 = exe[offset + 2] byte3 = exe[offset + 3] count = candidate_pointer_count(mode, byte2, byte3) if count <= 0 or count > 64: continue pointers: list[int] = [] for index in range(count): pointer_offset = offset + 4 + index * 4 if pointer_offset + 4 > len(exe): break pointers.append(struct.unpack_from(" list[dict[str, Any]]: script_table = read_json(OUT / "script_handler_table.json", {}) refs = [] for entry in script_table.get("entries") or []: if entry.get("opcodeHex") != "0x1c": continue for ref in entry.get("references") or []: word_va_hex = ref.get("wordVaHex") word_va = int(word_va_hex, 16) if isinstance(word_va_hex, str) else None raw = bytes_at_va(exe, sections, word_va, 4) if word_va is not None else b"" mode = raw[1] if len(raw) > 1 else None refs.append( { "streamKind": ref.get("streamKind"), "streamVaHex": ref.get("streamVaHex"), "wordIndex": ref.get("wordIndex"), "wordVaHex": word_va_hex, "valueHex": ref.get("valueHex"), "rawBytes": raw.hex(" ") if raw else "", "modeByteHex": f"0x{mode:02x}" if mode is not None else None, "modeValidForOpcode1c": mode in {0, 1, 2} if mode is not None else False, "source": ref.get("source"), "target": ref.get("target"), "interpretation": ( "low-byte pointer artifact, not a valid opcode 0x1c command" if mode not in {0, 1, 2} else "needs command-stream validation" ), } ) return refs def build_report() -> dict[str, Any]: exe = EXE.read_bytes() sections = read_sections(exe) handler_entry_value = dword_at_va(exe, sections, HANDLER_ENTRY_VA) candidates = scan_well_formed_opcode_blocks(exe, sections) low_byte_refs = collect_existing_low_byte_refs(exe, sections) mode_counts = Counter(row["modeHex"] for row in candidates) invalid_low_byte_ref_count = sum(1 for row in low_byte_refs if not row["modeValidForOpcode1c"]) return { "kind": "hwanse-field-rng-selector-opcode1c-review", "source": [ "Hwanse2.exe", "out/script_handler_table.json", "tools/build_field_rng_selector_opcode1c_review.py", ], "handler": { "handlerTableVaHex": hex32(HANDLER_TABLE_VA), "opcodeHex": f"0x{OPCODE:02x}", "handlerEntryVaHex": hex32(HANDLER_ENTRY_VA), "handlerEntryValueHex": hex32(handler_entry_value), "expectedHandlerVaHex": hex32(HANDLER_VA), "rngCallVaHex": hex32(RNG_CALL_VA), "activeCountGlobalHex": hex32(ACTIVE_COUNT_GLOBAL), "activeOrderGlobalHex": hex32(ACTIVE_ORDER_GLOBAL), "activeSlotWeightBaseHex": hex32(ACTIVE_SLOT_WEIGHT_BASE), }, "semantics": [ { "mode": 0, "summary": "selects by active object count: if active count is nonzero, index = activeCount - 1; pointer count comes from byte2.", }, { "mode": 1, "summary": "selects by active object/order aggregate. It reads active count 0x4576e8, active order 0x4576e9, and slot word values near 0x457756 before selecting a pointer range byte2..byte3.", }, { "mode": 2, "summary": "calls RNG helper 0x00427730 with byte2 as range and selects one of the following dword command pointers.", }, ], "summary": { "handlerEntryMatchesExpected": handler_entry_value == HANDLER_VA, "wellFormedOpcode1cBlockCount": len(candidates), "wellFormedModeCounts": dict(sorted(mode_counts.items())), "scriptHandlerTableLowByteReferenceCount": len(low_byte_refs), "invalidLowByteReferenceCount": invalid_low_byte_ref_count, "directFieldEncounterBindingFound": False, "classification": ( "handler-only-unbound" if not candidates else "well-formed-candidates-found-route-unbound" ), "decision": ( "Opcode 0x1c remains a handler-grounded selector primitive, but no well-formed command stream using it was found in the current static scan. " "The existing script_handler_table refs are low-byte pointer artifacts such as 1c f7 53 00, not executable opcode 0x1c commands. " "Do not promote it as field encounter evidence." ), }, "wellFormedCandidates": candidates, "scriptHandlerTableLowByteRefs": low_byte_refs, "knownGaps": [ "A runtime trace could still prove a dynamically materialized stream reaches opcode 0x1c.", "No static stream currently connects opcode 0x1c to walking step, map family, btl background, or monster formation data.", "The mode 1 aggregate source is grounded to active object globals, but its game-facing meaning is still not named.", ], } def render_html(report: dict[str, Any]) -> str: summary = report["summary"] handler = report["handler"] candidate_rows = [] for row in report["wellFormedCandidates"]: candidate_rows.append( "" f"{h(row['streamVaHex'])}" f"{h(row['section'])}" f"{h(row['modeHex'])}" f"{h(row['pointerCount'])}" f"{' '.join(f'{h(ptr)}' for ptr in row['pointerVasHex'][:8])}" "" ) if not candidate_rows: candidate_rows.append('well-formed opcode 0x1c command block 없음') ref_rows = [] for row in report["scriptHandlerTableLowByteRefs"]: status = "ok" if row["modeValidForOpcode1c"] else "bad" ref_rows.append( "" f"{h(row.get('wordVaHex'))}" f"{h(row.get('valueHex'))}" f"{h(row.get('rawBytes'))}" f"{h(row.get('modeByteHex'))}" f"{h(row.get('source'))} → {h(row.get('target'))}" f"{h(row.get('interpretation'))}" "" ) semantics = "".join( f"
  • mode {item['mode']}: {h(item['summary'])}
    • " for item in report["semantics"] ) return f""" Field RNG Selector Opcode 0x1c Review

    Field RNG Selector Opcode 0x1c Review

    필드 인카운트 쪽에 마지막으로 남았던 RNG selector 0x0040bdcc를 handler/opcode 단위로 분리한 리뷰입니다.

    {metric("handler entry matches", "yes" if summary["handlerEntryMatchesExpected"] else "no")} {metric("well-formed blocks", summary["wellFormedOpcode1cBlockCount"])} {metric("low-byte refs", summary["scriptHandlerTableLowByteReferenceCount"])} {metric("invalid low-byte refs", summary["invalidLowByteReferenceCount"])} {metric("field binding", "no" if not summary["directFieldEncounterBindingFound"] else "yes")}

    결론

    {h(summary["decision"])}

    • handler table: {h(handler["handlerTableVaHex"])}, opcode {h(handler["opcodeHex"])}, handler {h(handler["handlerEntryValueHex"])}
    • RNG call: {h(handler["rngCallVaHex"])}
    • active object globals: {h(handler["activeCountGlobalHex"])}, {h(handler["activeOrderGlobalHex"])}, {h(handler["activeSlotWeightBaseHex"])}

    Handler Semantics

      {semantics}

    Well-formed Opcode Blocks

    {''.join(candidate_rows)}
    streamsectionmodepointer countpointers

    기존 low-byte refs 재검토

    기존 script handler table의 refs는 dword low byte가 0x1c였다는 뜻일 뿐이다. 아래처럼 mode byte가 0xf7이면 opcode 0x1c handler가 정상 소비할 수 없다.

    {''.join(ref_rows)}
    wordvalueraw bytesmode bytesource/target metadatainterpretation

    Summary JSON

    {h(json.dumps(summary, ensure_ascii=False, indent=2))}
    """ def metric(label: str, value: Any) -> str: return f'
    {h(value)}
    {h(label)}
    ' def main() -> None: OUT.mkdir(parents=True, exist_ok=True) WEB.mkdir(parents=True, exist_ok=True) report = build_report() write_json(OUT / "field_rng_selector_opcode1c_review.json", report) html_text = render_html(report) (WEB / "field_rng_selector_opcode1c_review.html").write_text(html_text, encoding="utf-8") print("wrote field RNG selector opcode 0x1c review") if __name__ == "__main__": main()