#!/usr/bin/env python3 """Document the redraw consumer side of layer1 bit 0x40 map animation. Earlier reports prove that layer1 high bit 0x40 marks animated/redraw cells and that the generic VM has commands capable of writing the live map buffers. This report covers the other half of the pipeline: the viewport redraw consumer. The key distinction is important for later work: * this path proves how 0x40 cells are invalidated and redrawn; but * it does not prove which alternate tile/palette frame should be drawn. So this report should prevent us from repeatedly re-promoting redraw coverage as visible motion execution. """ from __future__ import annotations import html import json import sys 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 read_sections, va_to_offset # noqa: E402 LANDMARKS = [ { "name": "viewport dirty scan", "va": 0x00425403, "endVa": 0x00425620, "role": "Scans the 37x21 visible viewport and marks dirty cells.", }, { "name": "full surface dirty redraw", "va": 0x00425067, "endVa": 0x004250E4, "role": "Sets draw surface/mask, renders dirty rows, snapshots camera.", }, { "name": "dirty row renderer", "va": 0x00425163, "endVa": 0x0042530F, "role": "Reads live layer0 tile ids and draws dirty visible rows.", }, { "name": "active object projection", "va": 0x00424A2A, "endVa": 0x00424CD6, "role": "Projects object tile positions into viewport/screen positions.", }, { "name": "occlusion dirty projection", "va": 0x00424CD6, "endVa": 0x00425024, "role": "Projects object/occlusion coverage into the dirty work grid.", }, ] GLOBALS = { "liveLayer0Grid": 0x00595AF0, "liveLayer1FlagGrid": 0x0058D7D0, "dirtyWorkGrid": 0x005957D0, "mapWidth": 0x00595ADA, "mapHeight": 0x00595ADC, "cameraCurrentX": 0x004576DC, "cameraCurrentY": 0x004576DE, "cameraPreviousX": 0x00595ADE, "cameraPreviousY": 0x00595AE0, "drawSurfaceSlot": 0x0055B580, "drawDirtyMask": 0x0055B588, } def h(value: Any) -> str: return html.escape("" if value is None else str(value), quote=True) def hx(value: int | None) -> str | None: return None if value is None else f"0x{value:08x}" def write_json(path: Path, payload: Any) -> None: path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") def byte_snippet(exe: bytes, sections: list[dict[str, Any]], va: int, size: int = 64) -> str: offset = va_to_offset(sections, va) if offset is None: return "" return exe[offset : offset + size].hex(" ") def build_report() -> dict[str, Any]: exe = EXE.read_bytes() sections = read_sections(exe) landmark_rows = [] for row in LANDMARKS: landmark_rows.append( { **row, "vaHex": hx(row["va"]), "endVaHex": hx(row["endVa"]), "byteSnippet": byte_snippet(exe, sections, int(row["va"])), } ) steps = [ { "step": "clear dirty bits before viewport scan", "vaHex": "0x00425413", "evidence": "The 37x21 dirty work grid at 0x005957d0 is masked before the new viewport pass.", "meaning": "The routine starts from an invalidation pass, not from a frame-selection table.", }, { "step": "scan visible layer1 flags", "vaHex": "0x00425494", "evidence": "Reads WORD PTR [index*2 + 0x0058d7d0] and tests low byte with 0x40.", "meaning": "layer1 bit 0x40 is consumed as redraw/animation coverage over the current viewport.", }, { "step": "mark dirty work grid", "vaHex": "0x004254a5", "evidence": "When 0x40 is present, ORs the matching byte in 0x005957d0 with 0x01.", "meaning": "The consumer schedules redraw work. It does not choose a replacement tile id here.", }, { "step": "camera movement invalidation", "vaHex": "0x004254e0", "evidence": "Compares current camera 0x004576dc/de with previous 0x00595ade/e0, then compares visible layer0 cells.", "meaning": "Camera scrolling also marks dirty cells when the visible layer0 tile differs.", }, { "step": "render dirty rows from live layer0", "vaHex": "0x00425163", "evidence": "Row renderer reads live layer0 grid 0x00595af0 and combines it with the active surface slot.", "meaning": "The renderer draws whatever tile id is currently in the live layer0 grid.", }, { "step": "snapshot camera after redraw", "vaHex": "0x004250c4", "evidence": "After dirty row rendering, current camera is copied into 0x00595ade/e0.", "meaning": "The pass is a viewport redraw/cache maintenance step.", }, { "step": "object/occlusion dirty projection", "vaHex": "0x00424a2a", "evidence": "Active object positions are projected relative to the camera and coverage is written into dirty/occlusion buffers.", "meaning": "This explains foreground/actor redraw interaction, not map animation frame generation.", }, ] surfaces = [ { "surface": "layer1 0x40 viewport consumer", "promotion": "confirmed-redraw-consumer", "finding": "0x00425403 scans 37x21 visible layer1 cells and marks 0x005957d0 dirty bit 0x01 when layer1&0x40 is set.", "gap": "No alternate tile id, palette frame, or shift offset is selected in this path.", }, { "surface": "live layer0 row draw", "promotion": "confirmed-render-consumer", "finding": "0x00425163 draws dirty rows by reading live layer0 0x00595af0.", "gap": "If visible motion uses changing tile ids, the producer must mutate live layer0 before this renderer.", }, { "surface": "camera scroll invalidation", "promotion": "confirmed-redraw-cache", "finding": "0x00425403 also compares current/previous camera and marks dirty cells when visible layer0 differs.", "gap": "This is camera cache invalidation, not animation timing.", }, { "surface": "object/foreground dirty projection", "promotion": "confirmed-occlusion-redraw", "finding": "0x00424a2a..0x00425024 projects active-object coverage into redraw buffers.", "gap": "This handles actor/foreground redraw and does not bind animated map cells to frame loops.", }, ] return { "kind": "hwanse-map-animation-redraw-consumer-review", "status": "redraw-consumer-grounded-visible-motion-producer-unbound", "source": [ "Hwanse2.exe", "tools/build_map_animation_redraw_consumer_review.py", "out/map_animation_tile_review.json", "out/map_animation_live_buffer_writer_review.json", ], "globals": {key: hx(value) for key, value in GLOBALS.items()}, "summary": { "viewportTileWidth": 37, "viewportTileHeight": 21, "layer1AnimatedFlagBit": "0x40", "dirtyGridBitFor0x40": "0x01", "redrawPathGrounded": True, "layer1AnimatedFlagConsumerGrounded": True, "liveLayer0RendererGrounded": True, "alternateTileSelectionFound": False, "visibleMotionProducerFound": False, "decision": ( "0x40 cells are definitely consumed by the viewport redraw path, but this consumer only invalidates/redraws. " "Visible motion still needs either a live layer0 mutation producer or a draw-time tile transform that is not proven here." ), }, "landmarks": landmark_rows, "steps": steps, "surfaces": surfaces, "nextFrontier": [ "Inspect draw-time tile conversion under/after 0x00425163 and 0x004175d3 for frame-counter-based tile transforms.", "Search for a timer/tick path that mutates 0x00595af0 before the redraw consumer runs.", "If static route remains blocked, runtime-watch 0x00595af0 on map1_01a/map1_02b during one visible animation loop.", ], } def render_html(report: dict[str, Any]) -> str: summary = report["summary"] cards = [ ("status", report["status"]), ("viewport", f"{summary['viewportTileWidth']}x{summary['viewportTileHeight']} tiles"), ("0x40 consumer", "grounded" if summary["layer1AnimatedFlagConsumerGrounded"] else "missing"), ("layer0 renderer", "grounded" if summary["liveLayer0RendererGrounded"] else "missing"), ("alternate tile", "found" if summary["alternateTileSelectionFound"] else "not found"), ("producer", "found" if summary["visibleMotionProducerFound"] else "unbound"), ] card_html = "".join(f"
{h(k)}{h(v)}
" for k, v in cards) global_rows = "".join( f"{h(k)}{h(v)}" for k, v in report["globals"].items() ) step_rows = "".join( "" f"{h(row['step'])}
{h(row['vaHex'])}" f"{h(row['evidence'])}" f"{h(row['meaning'])}" "" for row in report["steps"] ) surface_rows = "".join( "" f"{h(row['surface'])}" f"{h(row['promotion'])}" f"{h(row['finding'])}" f"{h(row['gap'])}" "" for row in report["surfaces"] ) landmark_rows = "".join( "" f"{h(row['name'])}
{h(row['vaHex'])}..{h(row['endVaHex'])}" f"{h(row['role'])}" f"{h(row['byteSnippet'])}" "" for row in report["landmarks"] ) frontier = "".join(f"
  • {h(item)}
    • " for item in report["nextFrontier"]) payload = json.dumps(report, ensure_ascii=False) return f""" Map Animation Redraw Consumer Review
    index map review animation boundary live writers object-relative writes

    Map Animation Redraw Consumer Review

    {h(summary["decision"])}

    {card_html}

    Globals

    {global_rows}
    nameVA

    Execution Steps

    {step_rows}
    stepevidencemeaning

    Surfaces

    {surface_rows}
    surfacepromotionfindinggap

    Landmarks

    {landmark_rows}
    rangerolebyte snippet

    Next Frontier

    Raw JSON

    
  
    

    



"""


def main() -> int:
    OUT.mkdir(exist_ok=True)
    WEB.mkdir(exist_ok=True)
    report = build_report()
    write_json(OUT / "map_animation_redraw_consumer_review.json", report)
    html_text = render_html(report)
    print("map_animation_redraw_consumer_review ok")
    print(json.dumps(report["summary"], ensure_ascii=False, indent=2))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())