#!/usr/bin/env python3 """Scan object-relative live tile-write commands for map animation evidence. Opcode 0x58 writes an absolute tile coordinate. Opcodes 0x6b/0x76 write a tile relative to an active object. Because fire/waterfall animation could in theory be implemented through object-relative tile mutation, this report scans those two command layouts and checks whether they bind to known animated map roots. """ 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" MAP_ANIMATION_REVIEW = OUT / "map_animation_tile_review.json" sys.path.insert(0, str(ROOT / "tools")) from build_map_animation_tile_review import ( # noqa: E402 build_palette_binding_context, palette_command_alignment, palette_root_resource_binding, ) from probe_exe_scene_tables import offset_to_va, read_sections # noqa: E402 OPCODES = { 0x6B: { "handlerVaHex": "0x00408d10", "name": "active-object-relative live tile write", "filterMeaning": "actor id or 0xff wildcard", }, 0x76: { "handlerVaHex": "0x00409f23", "name": "active-object-list live tile write", "filterMeaning": "actor id, 0xfe current context, or 0xff wildcard", }, } def h(value: Any) -> str: return html.escape("" if value is None else str(value), quote=True) def hx(value: int | None, width: int = 8) -> str | None: return None if value is None else f"0x{value:0{width}x}" def read_json(path: Path, fallback: Any) -> Any: try: return json.loads(path.read_text(encoding="utf-8")) except FileNotFoundError: return fallback def write_json(path: Path, payload: Any) -> None: path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") def ascii_token_around(blob: bytes, offset: int, radius: int = 64) -> str: segment = blob[max(0, offset - radius) : min(len(blob), offset + radius)] runs: list[bytes] = [] current = bytearray() for byte in segment: if 0x20 <= byte <= 0x7E: current.append(byte) else: if len(current) >= 4: runs.append(bytes(current)) current.clear() if len(current) >= 4: runs.append(bytes(current)) text_runs: list[str] = [] for run in runs: try: text_runs.append(run.decode("ascii")) except UnicodeDecodeError: continue return " | ".join(text for text in text_runs if ".cns" in text.lower() or "map_" in text.lower()) def binding_digest(binding: dict[str, Any]) -> dict[str, Any]: return { "status": binding.get("status"), "rootVaHex": binding.get("rootVaHex"), "containingGroups": [ { "id": group.get("id"), "selector": group.get("selector"), "rootVaHex": group.get("rootVaHex"), "maps": group.get("maps", [])[:8], "animatedMaps": group.get("animatedMaps", []), "animatedTilesets": group.get("animatedTilesets", []), "linkClass": group.get("linkClass"), } for group in binding.get("containingGroups", [])[:3] ], "nearestGroups": [ { "id": group.get("id"), "selector": group.get("selector"), "rootVaHex": group.get("rootVaHex"), "distanceBytes": group.get("distanceBytes"), "maps": group.get("maps", [])[:8], "animatedMaps": group.get("animatedMaps", []), "animatedTilesets": group.get("animatedTilesets", []), "linkClass": group.get("linkClass"), } for group in binding.get("nearestGroups", [])[:3] ], "note": binding.get("note"), } def build_report() -> dict[str, Any]: blob = EXE.read_bytes() sections = read_sections(blob) animation_review = read_json(MAP_ANIMATION_REVIEW, {}) maps = animation_review.get("maps") or [] animated_tiles = { int(cell["layer0"]) for row in maps for cell in row.get("animatedCells", []) if isinstance(cell.get("layer0"), int) } binding_context = build_palette_binding_context(maps) data_section = next(section for section in sections if section["name"] == ".data") data_start = int(data_section["raw"]) data_end = min(len(blob) - 12, data_start + int(data_section["raw_size"])) rows: list[dict[str, Any]] = [] rejected_ascii: list[dict[str, Any]] = [] alignment_counts: Counter[str] = Counter() binding_counts: Counter[str] = Counter() opcode_counts: Counter[str] = Counter() animated_tile_direct_hits = 0 for offset in range(data_start, data_end): opcode = blob[offset] if opcode not in OPCODES: continue mode = blob[offset + 1] if mode not in (0, 1): continue actor_filter = blob[offset + 2] # Bytes +3..+5 are padding/reserved by the handler; it reads +6/+8/+0a. x_offset = struct.unpack_from(" str: summary = report["summary"] cards = [ ("status", report["status"]), ("candidates", summary["candidateCount"]), ("animated tile hits", summary["animatedTileDirectHitCount"]), ("animated root candidates", summary["animatedRootCandidateCount"]), ("binding", "proven" if summary["objectRelativeAnimationBindingProven"] else "unproven"), ] card_html = "".join(f"
{h(k)}{h(v)}
" for k, v in cards) rows = [] for row in report["rows"][:160]: binding = row.get("resourceBinding") or {} rows.append( "" f"{h(row['vaHex'])}
{h(row['opcodeHex'])}" f"{h(row['mode'])}
{h(row['modeMeaning'])}" f"{h(row['actorFilterHex'])}
{h(row['actorFilterMeaning'])}" f"{h(row['xOffset'])}, {h(row['yOffset'])}" f"{h(row['tile'])}
{h(row['tileHex'])}" f"{h(row['alignmentStatus'])}
{h(row['bestRootVa'])}" f"{h(binding.get('status'))}" f"{h(row['classification'])}" "" ) frontier = "".join(f"
  • {h(item)}
    • " for item in report["nextFrontier"]) payload = json.dumps(report, ensure_ascii=False) return f""" Map Animation Object-Relative Tile Write Review
    index map review animation boundary live buffer writers

    Map Animation Object-Relative Tile Write Review

    {h(summary['decision'])}

    {card_html}

    Layout

    {h(json.dumps(report['layout'], ensure_ascii=False, indent=2))}

    Candidate Commands

    {''.join(rows)}
    VA/opmodeactor filteroffsettilealignmentbindingclassification

    Next Frontier

      {frontier}

    Raw JSON

    
  
    

    



"""


def main() -> None:
    report = build_report()
    write_json(OUT / "map_animation_object_relative_tile_write_review.json", report)
    html_text = render_html(report)
    print("map_animation_object_relative_tile_write_review ok")
    print(json.dumps(report["summary"], ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()