#!/usr/bin/env python3 """Document the critical/alternate result presentation path. The sound-role report promotes attacker +0x62 bit 0x10 as the critical-like alternate result branch. This pass follows the spawned child script that the 0x10 consumer attaches through [0x442da1 + 0x150]. The resulting script is a palette operation, not a sprite label. """ from __future__ import annotations import html import json import sys from pathlib import Path from typing import Any ROOT = Path(__file__).resolve().parents[1] TOOLS = ROOT / "tools" OUT = ROOT / "out" if str(TOOLS) not in sys.path: sys.path.insert(0, str(TOOLS)) from build_battle_display_vm_static_decode import EXE, read_sections # noqa: E402 from build_battle_helper_body_review import ( # noqa: E402 CHILD_SCRIPT_TABLE_PTR_VA, disassemble, pe_sections, read_u32, ) from build_battle_helper_child_script_review import walk_child_script # noqa: E402 CHILD_SCRIPT_TABLE_OFFSET = 0x150 CRITICAL_CONSUMER_VA = 0x0040EF16 CRITICAL_CONSUMER_END_VA = 0x0040EFAA GENERIC_RUNNER_VA = 0x00402321 OPCODE_3B_HANDLER_VA = 0x00406313 OPCODE_38_HANDLER_VA = 0x004060DB PALETTE_BACKUP_HELPER_VA = 0x004012C0 PALETTE_DIRTY_FLAG = 0x00559D98 PALETTE_PTR = 0x004676E8 PALETTE_BACKUP_BUF = 0x00559DA1 def esc(value: Any) -> str: return html.escape(str(value if value is not None else "")) def hx(value: int | None) -> str: return "" if value is None else f"0x{value:08x}" def extract_key_rows(decoded: dict[str, Any]) -> list[dict[str, Any]]: out = [] for row in decoded.get("rows") or []: out.append( { "vaHex": row.get("vaHex"), "opcode": row.get("opcode"), "category": row.get("category"), "length": row.get("length"), "bytes": row.get("bytes"), "summary": row.get("summary"), "paletteStartHex": row.get("paletteStartHex"), "paletteCountHex": row.get("paletteCountHex"), "argHex": row.get("argHex"), "repeatCount": row.get("repeatCount"), "targetVaHex": row.get("targetVaHex"), "waitFrames": row.get("waitFrames"), } ) return out def build() -> dict[str, Any]: blob = EXE.read_bytes() _image_base, body_sections = pe_sections(blob) child_sections = read_sections(blob) child_table_base = read_u32(blob, body_sections, CHILD_SCRIPT_TABLE_PTR_VA) child_script_va = read_u32(blob, body_sections, child_table_base + CHILD_SCRIPT_TABLE_OFFSET) decoded = walk_child_script(blob, child_sections, child_script_va, max_steps=80) rows = extract_key_rows(decoded) palette_rows = [row for row in rows if str(row.get("category") or "").startswith("palette")] repeat_rows = [row for row in rows if row.get("opcode") == "0x06"] yield_count = sum(1 for row in rows if row.get("opcode") == "0x01") return { "version": 1, "kind": "hwanse-battle-critical-presentation-review", "source": [ "Hwanse2.exe", "out/battle_sound_role_review.json", "tools/build_battle_helper_child_script_review.py", ], "status": "critical-palette-flash-script-grounded", "consumer": { "consumerVaHex": hx(CRITICAL_CONSUMER_VA), "consumerEndVaHex": hx(CRITICAL_CONSUMER_END_VA), "flag": "attacker +0x62 bit 0x10", "alternateWlkOperand": "stream +3", "runnerVaHex": hx(GENERIC_RUNNER_VA), "childScriptTablePointerVaHex": hx(CHILD_SCRIPT_TABLE_PTR_VA), "childScriptTableOffsetHex": f"0x{CHILD_SCRIPT_TABLE_OFFSET:03x}", "childScriptIndex": CHILD_SCRIPT_TABLE_OFFSET // 4, "childScriptVaHex": hx(child_script_va), }, "paletteBinding": { "opcode3bHandlerVaHex": hx(OPCODE_3B_HANDLER_VA), "opcode38HandlerVaHex": hx(OPCODE_38_HANDLER_VA), "paletteBackupHelperVaHex": hx(PALETTE_BACKUP_HELPER_VA), "palettePointerVaHex": hx(PALETTE_PTR), "paletteBackupBufferVaHex": hx(PALETTE_BACKUP_BUF), "paletteDirtyFlagVaHex": hx(PALETTE_DIRTY_FLAG), "meaning": "0x3b backs up palette RGB triplets, 0x38 mode 1 applies the bright flash range, and 0x38 mode 2 performs a fade/step sequence before the object exits.", }, "scriptSummary": { "childScriptVaHex": hx(child_script_va), "stopReason": decoded.get("stopReason"), "instructionCount": decoded.get("instructionCount"), "opcodeCounts": decoded.get("opcodeCounts") or {}, "paletteRows": len(palette_rows), "yieldCount": yield_count, "repeatLoopCount": len(repeat_rows), "durationInterpretation": "The script has one immediate flash write, then a mode2 palette step at 0x004b85e8, a yield, and a repeat-loop count 8 back to that mode2 step. Exact wall-clock ms still depends on the display VM tick cadence.", }, "scriptRows": rows, "consumerDisassembly": disassemble(CRITICAL_CONSUMER_VA, CRITICAL_CONSUMER_END_VA), "opcode3bDisassembly": disassemble(OPCODE_3B_HANDLER_VA, 0x00406341), "opcode38Disassembly": disassemble(OPCODE_38_HANDLER_VA, 0x00406206), "conclusions": [ "Critical/alternate result presentation is not a MISS/HIT text sprite path.", "The 0x10 consumer plays alternate WLK id 14 and spawns generic runner 0x00402321.", "The spawned child script [0x442da1 + 0x150] resolves to 0x004b85cc.", "That child script backs up palette range 0x30 count 0xa0, applies palette transform mode 1 with arg 0xffffffff, then loops palette transform mode 2 with 32-step parameter eight times.", "Therefore the critical white flash should be implemented as a palette/full-screen flash presentation; only exact wall-clock duration remains approximate in the browser runner.", ], } def markdown(data: dict[str, Any]) -> str: lines = [ "# Battle Critical Presentation Review", "", f"- status: `{data['status']}`", f"- child script: `{data['consumer']['childScriptVaHex']}`", f"- child table index: `{data['consumer']['childScriptIndex']}`", "", "## Conclusions", "", ] lines.extend(f"- {item}" for item in data["conclusions"]) lines += [ "", "## Script Rows", "", "| VA | opcode | category | bytes | summary |", "| --- | --- | --- | --- | --- |", ] for row in data["scriptRows"]: lines.append( f"| `{row['vaHex']}` | `{row['opcode']}` | {row['category']} | `{row['bytes']}` | {row['summary']} |" ) lines += [ "", "## Consumer", "", "```asm", data["consumerDisassembly"], "```", "", "## Palette Opcode 0x3b", "", "```asm", data["opcode3bDisassembly"], "```", "", "## Palette Opcode 0x38", "", "```asm", data["opcode38Disassembly"], "```", ] return "\n".join(lines) + "\n" def html_page(data: dict[str, Any]) -> str: consumer_rows = "".join( f"{esc(key)}{esc(value)}" for key, value in data["consumer"].items() ) summary_rows = "".join( f"{esc(key)}{esc(value)}" for key, value in data["scriptSummary"].items() ) script_rows = "".join( "" f"{esc(row['vaHex'])}" f"{esc(row['opcode'])}" f"{esc(row['category'])}" f"{esc(row['bytes'])}" f"{esc(row['summary'])}" "" for row in data["scriptRows"] ) conclusions = "".join(f"
  • {esc(item)}
    • " for item in data["conclusions"]) return f""" Battle Critical Presentation Review

    Battle Critical Presentation Review

    홈 · 사운드 역할 · 결과 플래그 · JSON · MD

    Consumer

    {consumer_rows}

    Script Summary

    {summary_rows}

    Conclusions

    Script Rows

    {script_rows}
    VAopcodecategorybytessummary

    Consumer Disassembly

    {esc(data["consumerDisassembly"])}

    Palette Opcode 0x3b

    {esc(data["opcode3bDisassembly"])}

    Palette Opcode 0x38

    {esc(data["opcode38Disassembly"])}
    """ def main() -> None: data = build() (OUT / "battle_critical_presentation_review.json").write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") (OUT / "battle_critical_presentation_review.md").write_text(markdown(data), encoding="utf-8") (OUT / "battle_critical_presentation_review.html").write_text(html_page(data), encoding="utf-8") print("wrote battle_critical_presentation_review") if __name__ == "__main__": main()