#!/usr/bin/env python3
"""Build a review page for map animation source-offset hypotheses.
This report intentionally does not replace the palette redraw conclusion in
map_animation_tile_review. It is a visual/audit aid for the alternate idea
that some layer1 0x40 regions may select source tiles by shifting the layer0
source footprint.
"""
from __future__ import annotations
import html
import json
import sys
from collections import Counter
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
from decode_cns import decompress_cns, parse_image # noqa: E402
ROOT = Path(__file__).resolve().parents[1]
OUT = ROOT / "out"
EXTRACT_FLD = ROOT / "extract_fld"
TILE_SIZE = 16
def esc(value: object) -> str:
return html.escape(str(value))
def load_tileset_indices(stem: str) -> tuple[int, int, list[list[int]]]:
decoded = decompress_cns((EXTRACT_FLD / f"{stem}.cns").read_bytes())
width, height, _palette, pixels, bpp = parse_image(decoded)
stride = ((width * bpp + 31) // 32) * 4
rows: list[list[int]] = []
for y in range(height):
row = pixels[(height - 1 - y) * stride : (height - y) * stride]
if bpp == 8:
rows.append(list(row[:width]))
elif bpp == 4:
values = []
for byte in row[: (width + 1) // 2]:
values.append(byte >> 4)
if len(values) < width:
values.append(byte & 0x0F)
rows.append(values)
else:
raise ValueError(f"unsupported tileset bpp: {bpp}")
return width, height, rows
def block_stats(index_rows: list[list[int]], x: int, y: int, w: int, h: int) -> dict:
counts: Counter[int] = Counter()
for py in range(y * TILE_SIZE, (y + h) * TILE_SIZE):
for px in range(x * TILE_SIZE, (x + w) * TILE_SIZE):
counts[index_rows[py][px]] += 1
nonzero = Counter({key: value for key, value in counts.items() if key != 0})
return {
"nonzeroPixels": sum(nonzero.values()),
"paletteIndexCount": len(nonzero),
"topPaletteIndices": [
{"index": index, "pixels": count}
for index, count in nonzero.most_common(8)
],
}
def same_row_block_candidates(component: dict, columns: int, rows: int, index_rows: list[list[int]]) -> list[dict]:
block = component.get("sourceBlock")
if not block:
return []
width = block["width"]
height = block["height"]
source_y = block["sourceY"]
base_x = block["sourceX"]
if width <= 0 or height <= 0 or source_y + height > rows:
return []
step = width if columns % width == 0 else 1
candidates = []
for source_x in range(0, columns - width + 1, step):
stats = block_stats(index_rows, source_x, source_y, width, height)
if stats["nonzeroPixels"] <= 0 and source_x != base_x:
continue
candidates.append(
{
"sourceX": source_x,
"sourceY": source_y,
"width": width,
"height": height,
"baseTile": source_y * columns + source_x,
"deltaTiles": source_x - base_x,
"deltaPixels": (source_x - base_x) * TILE_SIZE,
"isCurrent": source_x == base_x,
**stats,
}
)
return candidates
def unique_row_patterns(component: dict) -> list[dict]:
counter: Counter[tuple[int | None, ...]] = Counter()
first_y: dict[tuple[int | None, ...], int] = {}
for row in component.get("rows", []):
pattern = tuple(row["tiles"])
counter[pattern] += 1
first_y.setdefault(pattern, row["y"])
patterns = []
for pattern, count in counter.most_common():
tiles = [tile for tile in pattern if tile is not None]
contiguous = bool(tiles) and all(tiles[index] == tiles[0] + index for index in range(len(tiles)))
columns = sorted({tile % 40 for tile in tiles}) if tiles else []
rows = sorted({tile // 40 for tile in tiles}) if tiles else []
patterns.append(
{
"firstMapY": first_y[pattern],
"repeatCount": count,
"width": len(pattern),
"tiles": list(pattern),
"contiguous": contiguous,
"sourceX": tiles[0] % 40 if contiguous and tiles else None,
"sourceY": tiles[0] // 40 if contiguous and tiles else None,
"sourceColumns": columns,
"sourceRows": rows,
}
)
return patterns
def row_shift_candidates(pattern: dict, columns: int, rows: int, index_rows: list[list[int]]) -> list[dict]:
if not pattern.get("contiguous"):
return []
width = pattern["width"]
source_y = pattern["sourceY"]
base_x = pattern["sourceX"]
if source_y is None or base_x is None or width <= 0:
return []
step = width if columns % width == 0 else 1
candidates = []
for source_x in range(0, columns - width + 1, step):
stats = block_stats(index_rows, source_x, source_y, width, 1)
if stats["nonzeroPixels"] <= 0 and source_x != base_x:
continue
candidates.append(
{
"sourceX": source_x,
"sourceY": source_y,
"width": width,
"height": 1,
"baseTile": source_y * columns + source_x,
"deltaTiles": source_x - base_x,
"deltaPixels": (source_x - base_x) * TILE_SIZE,
"isCurrent": source_x == base_x,
**stats,
}
)
return candidates
def classify_component(component: dict, row_patterns: list[dict], block_candidates: list[dict]) -> dict:
if component.get("sourceBlock") and len(block_candidates) >= 2:
return {
"class": "rectangular-offset-plausible",
"confidence": "visual-review-needed",
"reason": "The flagged placement is one rectangular source block, and same-row shifted blocks of equal size exist.",
}
contiguous_patterns = [pattern for pattern in row_patterns if pattern.get("contiguous")]
if contiguous_patterns and len(contiguous_patterns) == len(row_patterns):
return {
"class": "row-offset-or-row-cycle-plausible",
"confidence": "visual-review-needed",
"reason": "The region is built from repeated contiguous source rows; shifted row candidates can be inspected, but this is not one full rect.",
}
if contiguous_patterns:
return {
"class": "mixed-row-offset-candidate",
"confidence": "weak",
"reason": "Some rows are contiguous source rows, while others are repeated/filler patterns. A single shift rule is unlikely.",
}
return {
"class": "offset-shift-unproven",
"confidence": "weak",
"reason": "The flagged region does not map to a rectangular source block or clean contiguous source-row patterns.",
}
def build_review() -> dict:
source = json.loads((OUT / "map_animation_tile_review.json").read_text(encoding="utf-8"))
tileset_cache: dict[str, tuple[int, int, list[list[int]]]] = {}
maps = []
for row in source["maps"]:
tileset = row["sourceTileset"]
if tileset not in tileset_cache:
tileset_cache[tileset] = load_tileset_indices(tileset)
width_px, height_px, index_rows = tileset_cache[tileset]
columns = width_px // TILE_SIZE
source_rows = height_px // TILE_SIZE
components = []
for number, component in enumerate(row["placementComponents"], start=1):
block_candidates = same_row_block_candidates(component, columns, source_rows, index_rows)
patterns = unique_row_patterns(component)
for pattern in patterns:
pattern["shiftCandidates"] = row_shift_candidates(pattern, columns, source_rows, index_rows)
classification = classify_component(component, patterns, block_candidates)
components.append(
{
"componentIndex": number,
"mapBounds": {
"x0": component["x0"],
"y0": component["y0"],
"x1": component["x1"],
"y1": component["y1"],
"width": component["width"],
"height": component["height"],
"cellCount": component["cellCount"],
},
"sourceBlock": component.get("sourceBlock"),
"blockShiftCandidates": block_candidates,
"rowPatterns": patterns,
**classification,
}
)
maps.append(
{
"map": row["map"],
"sourceTileset": tileset,
"tilesetColumns": columns,
"tilesetRows": source_rows,
"animatedCellCount": row["animatedCellCount"],
"components": components,
}
)
counts = Counter(component["class"] for row in maps for component in row["components"])
return {
"version": 1,
"kind": "hwanse-map-animation-offset-shift-hypothesis-review",
"source": "out/map_animation_tile_review.json",
"summary": {
"mapCount": len(maps),
"componentCount": sum(len(row["components"]) for row in maps),
"classes": dict(sorted(counts.items())),
},
"notes": [
"This page tests an alternate offset-shift hypothesis for layer1 0x40 map animation.",
"It does not prove runtime tile replacement. The EXE-grounded consumer still shows 0x40 as dirty redraw and palette paths are still real.",
"A candidate here means the current source footprint has same-size or same-row visual neighbors that could be selected by an offset.",
"Use this with map_review tile selection to manually compare the map cell and source tileset positions.",
],
"maps": maps,
}
def render_candidate_canvas(row: dict, candidate: dict, class_name: str = "") -> str:
current = " current" if candidate.get("isCurrent") else ""
return (
f""
f""
f"#{candidate['baseTile']}"
f"dx {candidate['deltaTiles']} · nz {candidate['nonzeroPixels']}"
""
)
def render_block_candidates(row: dict, component: dict) -> str:
candidates = component.get("blockShiftCandidates") or []
if not candidates:
return "No rectangular same-row block-shift candidates.
"
rendered = "".join(render_candidate_canvas(row, candidate, "block") for candidate in candidates)
return f"{rendered}
"
def render_pattern(row: dict, pattern: dict) -> str:
tiles = " ".join("-" if tile is None else f"#{tile}" for tile in pattern["tiles"][:24])
if len(pattern["tiles"]) > 24:
tiles += " ..."
candidates = pattern.get("shiftCandidates") or []
candidate_html = (
f"{''.join(render_candidate_canvas(row, candidate, 'row') for candidate in candidates)}
"
if candidates
else "No clean row-shift candidates.
"
)
return (
""
f"row pattern y={pattern['firstMapY']} · repeat {pattern['repeatCount']} · "
f"{'contiguous' if pattern['contiguous'] else 'non-contiguous'}
"
f"{esc(tiles)}
"
f"{candidate_html}"
" "
)
def render_component(row: dict, component: dict) -> str:
bounds = component["mapBounds"]
block = component.get("sourceBlock")
block_text = (
f"({block['sourceX']},{block['sourceY']}) {block['width']}x{block['height']}"
if block
else "not rectangular"
)
patterns = "".join(render_pattern(row, pattern) for pattern in component["rowPatterns"][:12])
if len(component["rowPatterns"]) > 12:
patterns += f"+{len(component['rowPatterns']) - 12} more row patterns omitted.
"
return (
""
f"region {component['componentIndex']} · "
f"({bounds['x0']},{bounds['y0']})-({bounds['x1']},{bounds['y1']}) "
f"{bounds['width']}x{bounds['height']} · {bounds['cellCount']} cells
"
f"{esc(component['class'])} "
f"{esc(component['confidence'])}
"
f"{esc(component['reason'])}
"
f"current source block: {block_text}
"
"same-row block shift candidates
"
f"{render_block_candidates(row, component)}"
"row pattern shift candidates
"
f"{patterns}"
"{row['animatedCellCount']} animated cells · tileset {row['tilesetColumns']}x{row['tilesetRows']} tiles
"
f"{components}"
""
)
classes = ", ".join(f"{key}: {value}" for key, value in review["summary"]["classes"].items())
notes = "".join(f"{esc(note)}" for note in review["notes"])
doc = f"""
Map animation offset-shift hypothesis
Map animation offset-shift hypothesis
Classes: {esc(classes or '-')}
{''.join(rows)}
"""
(OUT / "map_animation_shift_hypothesis_review.html").write_text(doc, encoding="utf-8")
def main() -> None:
OUT.mkdir(exist_ok=True)
review = build_review()
(OUT / "map_animation_shift_hypothesis_review.json").write_text(
json.dumps(review, ensure_ascii=False, indent=2),
encoding="utf-8",
)
write_html(review)
if __name__ == "__main__":
main()