#!/usr/bin/env python3
"""Probe whether animated maps bind to palette/tile-write command roots.
This is intentionally narrower than the broader map animation reviews. It
asks one concrete question:
Do the selector/resource roots that load animated maps also contain the
candidate palette or tile-write commands that would drive visible motion?
The current answer is no. That means map resource loading is grounded, but the
per-frame animation loop is still somewhere else or encoded differently.
"""
from __future__ import annotations
import html
import json
from pathlib import Path
from typing import Any
ROOT = Path(__file__).resolve().parents[1]
OUT = ROOT / "out"
WEB = ROOT / "web"
def load_json(path: Path, fallback: Any) -> Any:
if not path.exists():
return fallback
return json.loads(path.read_text(encoding="utf-8"))
def h(value: Any) -> str:
return html.escape("" if value is None else str(value), quote=True)
def int_va(value: Any) -> int | None:
if isinstance(value, int):
return value
if isinstance(value, str) and value.startswith("0x"):
try:
return int(value, 16)
except ValueError:
return None
return None
def root_contains(root: dict[str, Any], va: int) -> bool:
start = int_va(root.get("rootVa")) or int_va(root.get("rootVaHex"))
end = int_va(root.get("rangeEndVa")) or int_va(root.get("rangeEndVaHex"))
return start is not None and end is not None and start <= va < end
def root_label(root: dict[str, Any]) -> str:
keys = ",".join(root.get("selectorKeys") or [])
return f"{root.get('rootVaHex', '')} {keys}".strip()
def command_va(row: dict[str, Any]) -> int | None:
return int_va(row.get("va") or row.get("vaHex"))
def palette_near_map(command: dict[str, Any], map_name: str) -> bool:
binding = command.get("resourceBinding") or {}
for record in binding.get("nearestAnimatedSceneRecords") or []:
if record.get("map") == map_name:
return True
return False
def palette_near_status(command: dict[str, Any]) -> str:
binding = command.get("resourceBinding") or {}
return binding.get("status", "")
def build() -> dict[str, Any]:
animation = load_json(OUT / "map_animation_tile_review.json", {})
roots = load_json(OUT / "selector_root_structure_review.json", {}).get("roots") or []
exe = load_json(OUT / "map_animation_exe_pattern_review.json", {})
palette_commands = ((animation.get("paletteCommandScan") or {}).get("commands") or [])
tile_write_scan = exe.get("tileWriteCommandScan") or {}
tile_write_rows: list[dict[str, Any]] = []
for key in [
"directAnimatedTileWrites",
"coordinateOnlyAlignedHits",
"rawAnimatedTileFalsePositiveSamples",
"asciiFalsePositiveSamples",
]:
for row in tile_write_scan.get(key) or []:
item = dict(row)
item["_bucket"] = key
tile_write_rows.append(item)
rows: list[dict[str, Any]] = []
for animated in animation.get("maps") or []:
map_name = animated.get("map", "")
tileset = animated.get("sourceTileset", "")
exact_roots = []
tileset_only_roots = []
for root in roots:
field_maps = root.get("fieldMaps") or []
linked_cns = root.get("linkedCns") or []
if map_name in field_maps or f"{map_name}.cns" in linked_cns:
exact_roots.append(root)
elif f"{tileset}.cns" in linked_cns:
tileset_only_roots.append(root)
palette_inside = []
palette_near = []
for command in palette_commands:
va = command_va(command)
if va is None:
continue
inside_roots = [root for root in exact_roots if root_contains(root, va)]
if inside_roots:
palette_inside.append(
{
"vaHex": command.get("va"),
"opcode": command.get("opcode"),
"kind": command.get("kind"),
"effectScope": (command.get("effectScope") or {}).get("class", ""),
"insideRoots": [root_label(root) for root in inside_roots],
}
)
if palette_near_map(command, map_name):
palette_near.append(
{
"vaHex": command.get("va"),
"opcode": command.get("opcode"),
"kind": command.get("kind"),
"effectScope": (command.get("effectScope") or {}).get("class", ""),
"bindingStatus": palette_near_status(command),
}
)
tile_inside = []
tile_near_nonanimated = []
for command in tile_write_rows:
va = command_va(command)
if va is None:
continue
inside_roots = [root for root in exact_roots if root_contains(root, va)]
if inside_roots:
tile_inside.append(
{
"vaHex": command.get("va") or command.get("vaHex"),
"bucket": command.get("_bucket"),
"tile": command.get("tile"),
"x": command.get("x"),
"y": command.get("y"),
"insideRoots": [root_label(root) for root in inside_roots],
}
)
binding = command.get("resourceBinding") or {}
if binding.get("status") == "resource-group-contained-nonanimated":
groups = binding.get("containingGroups") or []
for group in groups:
if map_name in (group.get("animatedMaps") or []):
tile_near_nonanimated.append(
{
"vaHex": command.get("va") or command.get("vaHex"),
"bucket": command.get("_bucket"),
"group": group.get("id"),
"rootVaHex": group.get("rootVaHex"),
}
)
rows.append(
{
"map": map_name,
"sourceTileset": tileset,
"animatedCellCount": animated.get("animatedCellCount"),
"componentCount": animated.get("componentCount"),
"exactResourceRootCount": len(exact_roots),
"exactResourceRoots": [
{
"rootVaHex": root.get("rootVaHex"),
"rangeEndVaHex": root.get("rangeEndVaHex"),
"selectorKeys": root.get("selectorKeys") or [],
"rootClass": root.get("rootClass"),
"fieldMaps": root.get("fieldMaps") or [],
"linkedCns": (root.get("linkedCns") or [])[:16],
}
for root in exact_roots
],
"tilesetOnlyRootCount": len(tileset_only_roots),
"tilesetOnlyRootSample": [
{
"rootVaHex": root.get("rootVaHex"),
"selectorKeys": root.get("selectorKeys") or [],
"fieldMaps": root.get("fieldMaps") or [],
}
for root in tileset_only_roots[:6]
],
"paletteCommandsInsideExactResourceRoots": palette_inside,
"paletteCommandsNearAnimatedSceneRecord": palette_near,
"tileWriteCommandsInsideExactResourceRoots": tile_inside,
"tileWriteNonanimatedContainmentHits": tile_near_nonanimated,
"bindingAssessment": (
"resource-root-unbound"
if not palette_inside and not tile_inside
else "candidate-command-inside-resource-root"
),
}
)
summary = {
"animatedMapCount": len(rows),
"mapsWithExactResourceRoot": sum(1 for row in rows if row["exactResourceRootCount"] > 0),
"mapsWithoutExactResourceRoot": sum(1 for row in rows if row["exactResourceRootCount"] == 0),
"paletteCommandInsideExactResourceRootCount": sum(
len(row["paletteCommandsInsideExactResourceRoots"]) for row in rows
),
"tileWriteCommandInsideExactResourceRootCount": sum(
len(row["tileWriteCommandsInsideExactResourceRoots"]) for row in rows
),
"paletteNearAnimatedSceneRecordCount": sum(
len(row["paletteCommandsNearAnimatedSceneRecord"]) for row in rows
),
"allExactResourceRootsUnbound": all(
not row["paletteCommandsInsideExactResourceRoots"]
and not row["tileWriteCommandsInsideExactResourceRoots"]
for row in rows
),
"decision": (
"animated map resource roots were found for most animated maps, but none of those exact root ranges "
"contain candidate palette/tile-write animation commands. The visible animation loop is therefore "
"not the same data root as the map resource package."
),
}
return {
"kind": "hwanse-map-animation-resource-binding-probe",
"status": "animated-resource-roots-found-animation-commands-unbound",
"source": [
"out/map_animation_tile_review.json",
"out/map_animation_exe_pattern_review.json",
"out/selector_root_structure_review.json",
"tools/build_map_animation_resource_binding_probe.py",
],
"summary": summary,
"rows": rows,
"nextFrontier": [
"Do not treat map resource opcode 0x10 roots as animation-loop roots.",
"Search for frame/tick consumers that touch the live map buffers after resource opcode 0x10 completes.",
"If static search remains blocked, narrow runtime tracing to map1_01a/map1_02b after load and watch tile/palette writes only.",
],
}
def render_html(report: dict[str, Any]) -> str:
summary = report["summary"]
cards = "".join(
f"{h(key)}{h(value)}
"
for key, value in summary.items()
if key != "decision"
)
rows = []
for row in report["rows"]:
roots = "
".join(
f"{h(root['rootVaHex'])} {h(','.join(root.get('selectorKeys') or []))}"
for root in row["exactResourceRoots"]
) or "none"
near = "
".join(
f"{h(cmd['vaHex'])} {h(cmd['opcode'])} {h(cmd['kind'])} / {h(cmd['bindingStatus'])}"
for cmd in row["paletteCommandsNearAnimatedSceneRecord"]
) or "none"
inside = []
for cmd in row["paletteCommandsInsideExactResourceRoots"]:
inside.append(f"palette {h(cmd['vaHex'])}")
for cmd in row["tileWriteCommandsInsideExactResourceRoots"]:
inside.append(f"tile {h(cmd['vaHex'])}")
inside_html = "
".join(inside) or "none"
rows.append(
""
f"{h(row['map'])}
{h(row['sourceTileset'])} | "
f"{h(row['animatedCellCount'])} | "
f"{roots} | "
f"{inside_html} | "
f"{near} | "
f"{h(row['bindingAssessment'])} | "
"
"
)
raw = json.dumps(report, ensure_ascii=False)
return f"""
Map Animation Resource Binding Probe
Map Animation Resource Binding Probe
{h(summary['decision'])}
{cards}
| map | cells | exact resource roots | commands inside exact roots | palette near scene | assessment |
|---|
{''.join(rows)}
"""
def main() -> None:
OUT.mkdir(exist_ok=True)
WEB.mkdir(exist_ok=True)
report = build()
(OUT / "map_animation_resource_binding_probe.json").write_text(
json.dumps(report, ensure_ascii=False, indent=2) + "\n",
encoding="utf-8",
)
html_text = render_html(report)
print("map_animation_resource_binding_probe ok")
if __name__ == "__main__":
main()