Files
zelda-1-prometeu-port/tools/extract_graphics.py
T

153 lines
7.2 KiB
Python

#!/usr/bin/env python3
"""Extract Zelda's raw NES pattern graphics without guessing sprite composition."""
import argparse
import hashlib
import json
from pathlib import Path
from PIL import Image, ImageDraw
ROOT = Path(__file__).resolve().parents[1]
ROM_SHA256 = "89232edf4f9b52e3cb872094bc78973de080befca2ddea893b6e936066514d4e"
SOURCE = "https://github.com/aldonunez/zelda1-disassembly/blob/master/src/bins.xml"
# Offsets are relative to PRG, excluding the 16-byte iNES header.
# PPU destinations checked against bank 1, bank 2 and bank 3 load routines.
BLOCKS = [
("demo_sprites", 19892, 2304, 0x0700),
("demo_background", 22196, 2080, 0x1700),
("common_sprites", 32895, 1792, 0x0000),
("common_background", 34687, 1792, 0x1000),
("common_misc", 36479, 224, 0x1F20),
("underworld_background", 49435, 2080, 0x1700),
("overworld_background", 51515, 2080, 0x1700),
("overworld_sprites", 53595, 1824, 0x08E0),
("underworld_sprites_358", 55419, 544, 0x09E0),
("underworld_sprites_469", 55963, 544, 0x09E0),
("underworld_sprites_common", 56507, 256, 0x08E0),
("underworld_sprites_127", 56763, 544, 0x09E0),
("bosses_1257", 57307, 1024, 0x0C00),
("bosses_3468", 58331, 1024, 0x0C00),
("boss_ganon", 59355, 1024, 0x0C00),
]
def decode(data):
"""NES 2bpp: eight low-plane bytes followed by eight high-plane bytes."""
if len(data) != 16:
raise ValueError("A pattern must contain exactly 16 bytes")
return [((data[y] >> (7 - x)) & 1) |
(((data[y + 8] >> (7 - x)) & 1) << 1)
for y in range(8) for x in range(8)]
def indexed(pixels, size):
image = Image.new("P", size)
# Neutral palette, deliberately not presented as original game colors.
image.putpalette([v for c in (0, 85, 170, 255) for v in (c, c, c)] + [0] * 756)
image.putdata(pixels)
return image
def encode(pixels):
"""Reverse decoding to verify the PNG preserves every source bit."""
return bytes(sum(((pixels[y * 8 + x] >> plane) & 1) << (7 - x)
for x in range(8)) for plane in range(2) for y in range(8))
def extract(rom_path, output):
rom = rom_path.read_bytes()
digest = hashlib.sha256(rom).hexdigest()
if digest != ROM_SHA256:
raise ValueError("ROM differs from the verified input; offsets must be validated first")
if rom[:4] != b"NES\x1a" or len(rom) != 16 + 8 * 16384:
raise ValueError("Unexpected ROM layout")
prg = rom[16:]
output.mkdir(parents=True, exist_ok=True)
manifest = {"rom_sha256": digest, "offset_basis": "PRG (file offset minus 16)",
"reference": SOURCE, "palette": "neutral grayscale indices 0..3",
"scope": "All 15 documented raw pattern blocks; not assembled scenes or animations",
"blocks": [], "ppu_sets": []}
all_tiles = []
for name, offset, length, ppu in BLOCKS:
block_dir = output / "tiles" / name
block_dir.mkdir(parents=True, exist_ok=True)
count = length // 16
sheet = Image.new("P", (128, ((count + 15) // 16) * 8))
sheet.putpalette(indexed([0] * 64, (8, 8)).getpalette())
records = []
for n in range(count):
source = prg[offset + n * 16:offset + (n + 1) * 16]
pixels = decode(source)
if encode(pixels) != source:
raise AssertionError("Tile roundtrip failed")
tile = indexed(pixels, (8, 8))
path = block_dir / f"{n:03d}.png"
tile.save(path)
# Validate the saved file, not only the in-memory decoder.
with Image.open(path) as saved:
if encode(list(saved.getdata())) != source:
raise AssertionError(f"PNG roundtrip failed: {path}")
sheet.paste(tile, ((n % 16) * 8, (n // 16) * 8))
all_tiles.append(tile)
records.append({"index": n, "prg_offset": offset + n * 16,
"file_offset": offset + 16 + n * 16,
"ppu_address": f"0x{ppu + n * 16:04X}",
"png": path.relative_to(output).as_posix(),
"sha256_2bpp": hashlib.sha256(source).hexdigest()})
sheets = output / "sheets"
sheets.mkdir(exist_ok=True)
sheet.save(sheets / f"{name}.png")
sheet.resize((sheet.width * 4, sheet.height * 4), Image.Resampling.NEAREST).save(
sheets / f"{name}@4x.png")
manifest["blocks"].append({"name": name, "prg_offset": offset,
"length": length, "tiles": records})
# Reconstruct the actual pattern memory used by each level, including gaps.
common = ["common_sprites", "common_background", "common_misc"]
sets = {"demo": common + ["demo_sprites", "demo_background"],
"overworld": common + ["demo_sprites", "overworld_background", "overworld_sprites"]}
for level in range(1, 10):
enemies = "127" if level in (1, 2, 7) else "358" if level in (3, 5, 8) else "469"
boss = "bosses_1257" if level in (1, 2, 5, 7) else "bosses_3468" if level != 9 else "boss_ganon"
sets[f"dungeon_{level}"] = common + ["underworld_background",
"underworld_sprites_common", f"underworld_sprites_{enemies}", boss]
(output / "ppu").mkdir(exist_ok=True)
for name, names in sets.items():
memory = bytearray(8192)
for block_name in names:
_, offset, length, ppu = next(b for b in BLOCKS if b[0] == block_name)
memory[ppu:ppu + length] = prg[offset:offset + length]
for table, base in (("sprites", 0), ("background", 4096)):
sheet = indexed([0] * (128 * 128), (128, 128))
for n in range(256):
tile = indexed(decode(memory[base + n * 16:base + (n + 1) * 16]), (8, 8))
sheet.paste(tile, ((n % 16) * 8, (n // 16) * 8))
sheet.save(output / "ppu" / f"{name}_{table}.png")
manifest["ppu_sets"].append({"name": name, "blocks_in_load_order": names})
width = 640
height = sum((((length // 16 + 15) // 16) * 24 + 32) for _, _, length, _ in BLOCKS)
overview = Image.new("RGB", (width, height), "#252525")
draw = ImageDraw.Draw(overview)
y = 0
for name, _, length, _ in BLOCKS:
draw.text((8, y + 8), f"{name} ({length // 16} tiles)", fill="white")
with Image.open(output / "sheets" / f"{name}.png") as sheet:
zoom = sheet.convert("RGB").resize((384, sheet.height * 3), Image.Resampling.NEAREST)
overview.paste(zoom, (8, y + 28))
y += ((length // 16 + 15) // 16) * 24 + 32
overview.save(output / "overview.png")
manifest["tile_count"] = len(all_tiles)
manifest["unique_tile_count"] = len({bytes(t.getdata()) for t in all_tiles})
manifest["png_count"] = len(list(output.rglob("*.png")))
(output / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n")
print(json.dumps({k: manifest[k] for k in ("tile_count", "unique_tile_count", "png_count")}, indent=2))
if __name__ == "__main__":
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--rom", type=Path, default=ROOT / ".tmp/zelda-1.nes")
parser.add_argument("--output", type=Path, default=ROOT / "extracted/graphics")
args = parser.parse_args()
extract(args.rom, args.output)