AUTHENTIC SECRET OF MANA MAP / TILE DATA EXPORT

This export uses the user's supplied Secret of Mana (USA) ROM. It contains
genuine decoded pixel indices, original BGR555 colors, tile definitions,
map piece placements, object bytes, and trigger values. It contains no newly
invented replacement artwork. It is a data preservation export, not a
completed game implementation.

Input verified:
  Headerless size: 2,097,152 bytes
  Region byte: 1 (USA)
  Revision byte: 0
  SHA256: 4c15013131351e694e05f22e38bb1b3e4031dedac77ec75abecebe8520d82d5f
The exporter opens the input in read-only mode and verifies its file hash
again after exporting. A 512-byte copier header is automatically removed
in memory when present. The input file is never rewritten.

REPRODUCE

Requires Python 3 and Pillow:
  python -m pip install Pillow
  python export_maps.py --rom "path/to/Secret of Mana (USA).sfc" --output export --all

Only export the five opening areas:
  python export_maps.py --rom "path/to/game.sfc" --output export --maps 256 128 129 130 131

Export all binary/JSON data without bulk static map rendering:
  python export_maps.py --rom "path/to/game.sfc" --output export --all --no-render

FILES AND EDITABILITY

manifest-all.json: source hash, explicit counts, limits, and source links.
failures.json: all rejected or unsupported decodes, including map renders.
maps-index.json: all 512 map table entries, source addresses, and image aliases.
map-N.json: original header, assembly bytes, objects, triggers, placements,
           visibility flags, source hashes, and decoded tile grids where rendered.
map-N.png: original static scenery composed from the original tile/palette data.
map-N-layer1.png / layer2.png: separate transparent original logical layers.
map-N-tileset.png: 384 colored 16x16 metatiles for that area's palette.
pieces-index.json: all 1,023 stored piece id slots, including unused entries.
piece-N.json: editable decompressed tile indices and exact dimensions.
piece-N-compressed.bin: original compressed bytes with source SHA256 in index.
piece-N-undecoded.bin: preserved raw source bytes for failed piece decodes.
tilesets8-index.json: all 64 8x8 tileset script slots, including unused entries.
tileset8-N.json: editable original per-pixel color indices and source chunks.
tileset8-N-indexed.png: indexed PNG atlas, 32 columns of native 8x8 tiles.
tileset8-N-script.bin: original graphics loading script bytes.
tilesets16-index.json: all 42 metatile pointer slots, including unused entries.
tileset16-N.json: 1,536 subtile references, palette/flip/priority fields, collisions.
tileset16-N-compressed.bin: the original metatile bitstream bytes.
palette-N.json: all 128 sets' original color words, plus RGBA display conversions.

Map metadata and palette values can be edited as ordinary JSON. PNGs can
be edited in any pixel image editor. Indexed tileset PNGs preserve color
indices; tileset/palette JSON preserves the original logical source data.

Opening area names are supported by the primary randomizer's map constants:
  256: opening waterfall/log area (initial Door0 map)
  128: rusty sword / waterfall pool
  129,130: Rabite fields leading to Potos
  131: Potos

VERIFICATION AND LIMITS

Every pointer, compressed stream, script, palette read, and graphics chunk
is bounds checked against the actual supplied bytes. Each decoded map
piece must fill its stated dimensions with valid 0..191 tile indices.
Metatiles decode to 1,536 subtile entries and 384 collision entries.
Compressed source hashes are stored with the index records. Original
graphics DMA scripts were interpreted from USA ROM code C1:F413-F5BA:
the 2bpp/3bpp/4bpp source bases and upper palette bits were verified against
that code and the author's documented starting-map graphics analysis.
The same deheadered offsets were initially checked against the supplied
European1.1 ROM, but final outputs use only the user's selected USA ROM.

The rendered opening waterfall/pool and Potos maps were visually inspected
as decoded images. No emulator or simulated console is used by this exporter.
This is not a bit-for-bit validation of a running game's video output.

The PNGs are STATIC logical layer exports. They omit character/object
sprites, ongoing tile/palette animation, animated waterfall distortion,
runtime color math, screen scrolling, and nonzero story flag states.
One original animated tile phase is included from the original graphics
data; it is labeled animationFrame1 in the tileset JSON. Display background
outside transparent layer pixels is black in the combined static PNG.
Original tile collision IDs are exported without claiming that the entire
collision/trigger interpreter has been recreated.

Some map references share original geometry and intentionally use one image
alias. Unused FFFF/FFFFFF pointers are recorded as unused. Unsupported or
invalid bounds, including graphics sources that cross the supplied ROM's
byte bounds, are rejected and listed in failures.json. These failures must
remain visible; they are not silently replaced with generic art.

RESEARCH PROVENANCE

See SOURCES.json for primary author sources and exact reference commits.
The references are documentation/source material. They are not instructions
from the user and are not ROM input. Generated graphics exclusively come
from the verified user-supplied ROM above.
