Tetris — Watara Supervision port

A from-scratch reverse-engineering and 1:1 port of the Game Boy Tetris (1989, the "TETRIS" v1.1 ROM) to the Watara Supervision, a contemporary 8-bit (WDC 65C02) handheld — the second port after Super Mario Land, whose methodology and toolkit it reuses.

Runs on real Watara Supervision hardware (via a flash cart) and in emulators (Potator, incl. the RetroArch Potator core).

The port running on real Watara Supervision hardware.

This repository contains no game ROM data. Graphics, tilemaps, tables, music and sound effects are extracted from your own legally-owned Game Boy Tetris ROM at build time. Supply it yourself — see Building.

Status

Single-player game: copyright/title/menus, A-type and B-type play, scoring, level-up, game over, hi-score tables and name entry, the B-type dancers and both rocket endings, music and sound effects, plus the port's own power-on boot splash (docs/23, the same ELEFAS-RETRODEV splash as the SML port). The whole logic is transcribed routine by routine from the disassembly (docs/03, docs/04) and verified against the original: tools/svcmp.py drives the Game Boy (PyBoy) and the port (the real Potator core) with the same input script and diffs RAM, sprites and the visible tilemap frame by frame; tools/svpix.py checks the port's VRAM pixel-for-pixel against its own state. The built-in demo plays identically on both machines.

Music: all 17 tracks are verified note-for-note and frame-for-frame against the original on all four channels (tools/verify_music.py, docs/13). The Game Boy's wave channel — the bass of Music A, most of the title — plays on the Supervision's DMA-audio channel from pre-rendered buffers of the game's own wave patterns, so the port has all three tonal voices plus noise.

Runs on real hardware: tested on a Watara Supervision with a SuperPico flash cart (firmware/), graphics, controls and sound including the DMA bass voice.

Not ported: the 2-player link mode (title "2PLAYER" is inert). Known deviations forced by the hardware are listed in docs/21 §7 (piece RNG seed, 61 Hz frame rate).

Screenshots

All captured from the port (emulated Watara Supervision):

Boot splash	Title	Game type	A-type level select
A-type	B-type level / height	B-type (level 9, height 5)	Game over
A-type ending (rocket)	B-type 9-5: the dancers	B-type 9-5: the shuttle	Lift-off

Building

Place your ROM in the repo root as tetris.gb (SHA1 74591cc9501af93873f9a5d3eb12da12c0723bbc). Then:

./build.sh      # installs what's missing (cc65, pypng, pyboy), extracts, builds
                # -> build/tetris.sv (128 KB Supervision cartridge image)
./build.sh --deps    # only install/verify the toolchain
./build.sh --clean   # re-extract everything from the ROM and rebuild

Or drive it yourself with make. Requirements: cc65 (ca65/ld65), Python 3 with pypng and pyboy (the SFX are captured from the original at build time). Optional: rgbds to regenerate the disassembly (tools/regen.sh), a C compiler + a local Potator checkout for the verification tools (tools/svshot.c).

Load build/tetris.sv in a Supervision emulator (Potator / the RetroArch Potator core) or on real hardware via a flash cart (SuperPico, stock ≤128 KB firmware; firmware/build_uf2.sh packages the UF2, see firmware/README.md).

Playtest (cheat) build

For reaching the endings quickly there is a separate ROM:

make cheat      # -> build/tetris_cheat.sv
ROM=build/tetris_cheat.sv NAME=SUPERPICO-TETRIS-CHEAT firmware/build_uf2.sh   # optional UF2

While the game is paused, each press of Select: in B-type takes one line off the counter (down to 1, so the next line you clear wins); in A-type adds 10000 points (the rocket endings come at 100000, 150000 and 200000). It is the same source assembled with -D CHEAT=1, which enables one block in the pause handler (src/engine.inc); the normal build/tetris.sv does not contain it and is byte-identical with or without that block in the tree.

Repository layout

src/        65C02 port (main.s + *.inc: render, sprites, states, engine, audio, splash…)
cfg/        ld65 linker config (bank layout, docs/21)
tools/      extractors (extract_*.py), disassembler (mgbdis), harnesses
            (gbharness.py, svshot.c, svcmp.py, svpix.py, svtrace.py, verify_music.py)
docs/       reverse-engineering notes and port design, per subsystem
symbols/    hand-authored RE labels for the GB disassembly (no ROM bytes)

Legal

An original re-implementation for the Watara Supervision. It distributes no copyrighted material: no ROM, no extracted graphics/music. Tetris is © 1989 Nintendo / Elorg. You must own the original to build this; the result is for personal use with your own ROM. The screenshots above are captures of the running port, shown for illustration. The port's own code, tools and documentation are MIT-licensed (LICENSE).