#!/usr/bin/env python3
"""Generate a review page for decompressed CNS tilemap payload layout."""
from __future__ import annotations
import argparse
import html
import json
import struct
from collections import Counter
from pathlib import Path
from typing import Any
from decode_cns import decompress_cns
ROOT = Path(__file__).resolve().parents[1]
OUT = ROOT / "out"
def hex_byte(value: int) -> str:
return f"0x{value:02x}"
def hex_off(value: int) -> str:
return f"0x{value:04x}"
def hex_word(value: int) -> str:
return f"0x{value:04x}"
def read_words(decoded: bytes, offset: int, count: int) -> list[int]:
return list(struct.unpack_from(f"<{count}H", decoded, offset))
def detect_tilemap(decoded: bytes) -> dict[str, Any] | None:
if len(decoded) >= 4:
width = int.from_bytes(decoded[0:2], "little")
height = int.from_bytes(decoded[2:4], "little")
tile_count = width * height
expected = 4 + tile_count * 4
if 0 < width <= 256 and 0 < height <= 256 and len(decoded) == expected:
return {
"headerBytes": 4,
"width": width,
"height": height,
"tileCount": tile_count,
"variant": "standard-u16-size",
}
if len(decoded) >= 2:
width = decoded[0]
height = decoded[1]
tile_count = width * height
expected = 2 + tile_count * 4
if 0 < width <= 256 and 0 < height <= 256 and len(decoded) == expected:
return {
"headerBytes": 2,
"width": width,
"height": height,
"tileCount": tile_count,
"variant": "compact-u8-size",
}
return None
def range_row(label: str, start: int, size: int, role: str, sample: str) -> dict:
end = start + size - 1 if size else start
return {
"label": label,
"start": start,
"end": end,
"startHex": hex_off(start),
"endHex": hex_off(end),
"size": size,
"sizeHex": hex_off(size),
"role": role,
"sample": sample,
}
def layer_stats(values: list[int]) -> dict:
counts = Counter(values)
nonzero = sum(1 for value in values if value)
return {
"count": len(values),
"unique": len(counts),
"zeroCount": counts.get(0, 0),
"nonzeroCount": nonzero,
"topValues": [
{"value": value, "valueHex": hex_word(value), "count": count}
for value, count in counts.most_common(12)
],
}
def sample_grid(values: list[int], width: int, height: int, max_w: int = 32, max_h: int = 24) -> list[list[int]]:
step_x = max(1, (width + max_w - 1) // max_w)
step_y = max(1, (height + max_h - 1) // max_h)
rows = []
for y in range(0, height, step_y):
row = []
for x in range(0, width, step_x):
row.append(values[y * width + x])
rows.append(row)
return rows
def summarize_tilemap(path: Path) -> dict | None:
raw = path.read_bytes()
decoded = decompress_cns(raw)
detected = detect_tilemap(decoded)
if detected is None:
return None
header_bytes = detected["headerBytes"]
width = detected["width"]
height = detected["height"]
tile_count = detected["tileCount"]
layer0_start = header_bytes
layer0_size = tile_count * 2
layer1_start = layer0_start + layer0_size
layer1_size = tile_count * 2
layer0 = read_words(decoded, layer0_start, tile_count)
layer1 = read_words(decoded, layer1_start, tile_count)
if header_bytes == 4:
header_sample = (
f"width={width} ({decoded[0]:02x} {decoded[1]:02x}), "
f"height={height} ({decoded[2]:02x} {decoded[3]:02x})"
)
else:
header_sample = f"width={width} ({decoded[0]:02x}), height={height} ({decoded[1]:02x})"
return {
"name": path.name,
"path": str(path.relative_to(ROOT)),
"compressedBytes": len(raw),
"decodedBytes": len(decoded),
**detected,
"bytesPerTilePerLayer": 2,
"bytesPerTileTotal": 4,
"ranges": [
range_row(
"header",
0,
header_bytes,
"map dimensions in tiles; the map name is not stored here",
header_sample,
),
range_row(
"layer0",
layer0_start,
layer0_size,
"base tile word grid used for the visible lower map layer",
", ".join(hex_word(value) for value in layer0[:8]),
),
range_row(
"layer1",
layer1_start,
layer1_size,
"upper/flag word grid; original loader copies this grid to the collision flag buffer",
", ".join(hex_word(value) for value in layer1[:8]),
),
],
"layer0Stats": layer_stats(layer0),
"layer1Stats": layer_stats(layer1),
"layer0Sample": sample_grid(layer0, width, height),
"layer1Sample": sample_grid(layer1, width, height),
"firstCells": [
{
"index": index,
"x": index % width,
"y": index // width,
"layer0": layer0[index],
"layer0Hex": hex_word(layer0[index]),
"layer1": layer1[index],
"layer1Hex": hex_word(layer1[index]),
}
for index in range(min(16, tile_count))
],
"notes": [
"The compressed .cns stream must be decompressed before these offsets apply.",
"The file name or FLD entry name supplies the map name; no map-name string is present in this tilemap payload.",
"Layer1 is confirmed as the source copied by the original map loader into the collision flag grid, but the exact pass/block test is EXE collision-helper logic.",
],
}
def build_summary(src_dir: Path) -> dict:
rows = []
for path in sorted(src_dir.glob("*.cns")):
item = summarize_tilemap(path)
if item is not None:
rows.append(item)
counts = Counter(
"field-map" if row["name"].startswith("map") else "battle-background" if row["name"].startswith("btl_") else "other"
for row in rows
)
return {
"scope": "decompressed CNS tilemap payload byte layout",
"sourceDir": str(src_dir.relative_to(ROOT)),
"tilemapCount": len(rows),
"counts": dict(sorted(counts.items())),
"formatSummary": {
"standard": "u16 width, u16 height, u16 layer0[width*height], u16 layer1[width*height]",
"compact": "u8 width, u8 height, u16 layer0[width*height], u16 layer1[width*height]",
"nameSource": "CNS file name / GENSE.FLD entry name, not decompressed payload bytes",
"collisionSource": "CNS layer1 word grid is copied to the original collision flag buffer; EXE helper interprets it",
},
"rows": rows,
}
def html_page(summary: dict) -> str:
data = json.dumps(summary, ensure_ascii=False)
return "\n".join([
"",
'',
"",
' ',
' ',
" CNS Tilemap Format",
" ",
"",
"",
" ",
" ",
"
",
"
Byte Ranges After Decompression
",
"
Layer1 / Collision Flag Source Sample Grid
",
"
",
"