Sonic Pocket Redux
Sonic Pocket Redux is a native PC port of Sonic the Hedgehog: Pocket Adventure with 16:9 support and drop dash.
- Type: PC port
- Game: Sonic the Hedgehog: Pocket Adventure
- Runs on Windows and macOS
- By pastamania
- Latest release v0.1.0, 2026-11-13
- Source: https://github.com/pastamania/sonicpocketredux
README
Sonic Pocket Adventure Recompilation Redux
This is an upgraded version of GlitchKiss's Sonic Pocket recompliation from https://github.com/GLITCHKISS/Sonic-Pocket.
It adds 16:9/16:10 support, as well as 60/90/120hz, as well as the dropdash from more recent games.
- Is this AI Generated? Oooooh yeah. A ton of Claude'ing going on here. If someone ever does this properly, play that instead. --
A static recompilation of Sonic the Hedgehog: Pocket Adventure (Neo Geo Pocket Color) to native C++.
The game's TLCS-900/H machine code is translated ahead of time into C++ functions, one per routine, and compiled into a native PC executable. The translated code runs on a small Neo Geo Pocket Color runtime that provides the video chip, sound chips, timers, interrupts, save flash and BIOS.
Status
- Playable.
sonic-pocketruns the recompiled game in an SDL3 window with keyboard and gamepad input, sound and persistent save data. - Exact.
spa-verifyruns the recompiled game and an interpreter side by side and checks that registers, cycle counts, RAM and video memory stay identical every frame. Currently 1200 frames (boot, SEGA logo, title) are in exact lockstep. - Checked against a reference. With the interpreter, the machine's work RAM matches a BizHawk (Mednafen) capture byte for byte for 1077 of 1198 frames after boot; the remaining differences are understood timing details.
- Nearly all native. All 2,771 known routines are recompiled. Only the flash-save routine the game copies into RAM and the BIOS entry points run through the interpreter.
Known Bugs
- In the final level, Eggman vanishes before reaching the right hand side in widescreen mode.
The generated code is correct but machine-shaped: every instruction calls the
CPU core's handler for it. Next steps are lifting it to plain, readable C++
and then rebuilding game systems (player, objects, collision) as structured
code, each change checked by the lockstep verifier. See
docs/recomp-plan.md.
How it works
cartridge ──► spa-recomp ──► generated C++ (one function per routine)
│
▼
runtime: TLCS-900/H CPU state + interpreter fallback, K2GE video,
T6W28 PSG + DACs, Z80 sound CPU, timers/interrupts, flash,
high-level BIOS ──► SDL3 frontend
src/cpu/tlcs900/: MAME's TLCS-900/H core (BSD-3), adapted to run standalone. Its opcode tables drive both the interpreter and the recompiler.src/ngpc/: the machine: TMP95C061 timers and interrupts, K2GE video, T6W28 sound (from MAME), Z80 (superzazu/z80, MIT), flash and a high-level BIOS matching the Mednafen/BizHawk core.src/recomp/:spa-recomp, which decodes the ROM with the interpreter's tables and emits C++ with native control flow.src/recomp_rt/: runtime for the generated code: dispatch, calls and returns, interpreter fallback and the game thread.src/apps/:sonic-pocket(the game),spa-verify(lockstep check) andngpc-run(headless interpreter runs and RAM dumps).config/recomp/functions.txt: routine entry points, generated bytools/recomp_seeds.pyfrom ValleyBell's SPA disassembly.docs/notes/: reverse-engineering notes on the game's systems (scheduler, VBlank, input, player, collision, camera).scripts/bizhawk-dump-reference.luaandtools/compare_ram_frames.py: reference captures from BizHawk and comparison against the machine.tools/rominfo.py: checks that a cartridge image is the expected release (config/rom.json).src/common/cartridge.*: the same check inside the program, and finding the cartridge (as a file or in a zip archive);tests/cartridge_test.cpptests it without a cartridge (ctest --test-dir build/recomp -C Release).tools/check_rom_free.py: looks for stretches of a cartridge in built files, to confirm that what is handed out holds none of the game (see "Building a version to hand out").NOTICE.txt: the licences of the third-party code in the program, which goes with every copy of it.assets/icon/andtools/make_icon_header.py: the program's icon.icon.pngis the source; the script makessonic-pocket.ico(compiled into the Windows exe bysonic-pocket.rc) andsrc/apps/window_icon.h(the window icon on macOS and Linux). Run it again after changingicon.png(needs ImageMagick).
Building
Requirements: a C++20 compiler (Visual Studio 2026 on Windows, Xcode command line tools on macOS, GCC or Clang on Linux), CMake 3.25+ and a legally obtained copy of the cartridge. SDL3 is downloaded automatically.
Windows:
cmake -S . -B build/recomp -G "Visual Studio 18 2026" -A x64 `
-DSPA_ROM="C:/path/to/Sonic The Hedgehog - Pocket Adventure (World) (En,Ja).ngc"
cmake --build build/recomp --config Release --target sonic-pocket -- /m:1
macOS and Linux:
cmake -S . -B build/recomp -DCMAKE_BUILD_TYPE=Release \
-DSPA_ROM="/path/to/Sonic The Hedgehog - Pocket Adventure (World) (En,Ja).ngc"
cmake --build build/recomp --target sonic-pocket
The recompiler runs as part of the build and writes the generated sources to
build/recomp/generated/. They are large, so the first build takes a while;
on low-power machines keep to one compiler process (/m:1 above, -j1 elsewhere).
On Linux, building SDL3 needs its usual development packages (on Debian and Ubuntu:
build-essential cmake libudev-dev libx11-dev libxext-dev libwayland-dev libxkbcommon-dev libasound2-dev libpulse-dev, see SDL's own docs/README-linux.md for the full list).
Only Windows is built by the CI; macOS and Linux are not tested there.
Building a version to hand out
The build above puts the game, recompiled from your cartridge, inside the program. That program is a translation of the game and is for your own use. To give the program to other people, build it without a cartridge:
cmake -S . -B build/player -G "Visual Studio 18 2026" -A x64 -DSPA_PLAYER=ON
cmake --build build/player --config Release --target sonic-pocket
(On macOS and Linux: cmake -S . -B build/player -DCMAKE_BUILD_TYPE=Release -DSPA_PLAYER=ON.)
Do not set SPA_ROM for this build, and use a build folder of its own. The program holds no
part of the game: whoever runs it supplies their own cartridge (see Playing), which it
interprets. It plays the same as the recompiled one (frame 600 of a run is identical to the
pixel) and costs a little more CPU.
Hand out sonic-pocket.exe, SDL3.dll and NOTICE.txt, which the build puts together in
build/player/Release/. Without a Windows machine, the "Windows player" workflow (Actions tab, Run workflow) builds the
same thing on GitHub and attaches SonicPocket-windows-x64.zip to the run. Download it, unzip
it, and run the check below on the unzipped folder before handing it on.
Then check that nothing of the cartridge got in:
python tools/check_rom_free.py --rom "path\to\cartridge.ngc" build\player\Release
It exits 0 when every file is clean. It looks for 32 or more bytes in a row that are in both the cartridge and a file, ignoring padding and regular tables such as counters, so it finds copied data and not code translated from the game's (which holds none of its bytes). A copy of 64 bytes or more that has any content is found; it is a check on the build, not a proof.
Playing
build\recomp\Release\sonic-pocket.exe "path\to\cartridge.ngc"
On macOS and Linux (single-configuration builds put the program straight in
build/recomp/):
build/recomp/sonic-pocket "path/to/cartridge.ngc"
The cartridge path is optional. Without it, the program looks for
Sonic The Hedgehog - Pocket Adventure (World) (En,Ja).ngc, and for a zip archive of that
name (... (En,Ja).zip, holding the cartridge under any name), in the folder the program is in
and then in the folder it was started from. If neither is there it uses the place it last found
the cartridge (the rom= line of settings.txt in the preferences folder, below), and if that
fails too it opens a file dialog. A file is accepted only if its size and CRC-32 are those of the
World release in config/rom.json; a file that is not says so and the
dialog asks again. Wherever the cartridge is found it is remembered, so the dialog is only
shown when the cartridge has moved. A cartridge named on the command line may also be a zip
archive, and is checked in the same way.
| Action | Keyboard | Gamepad |
|---|---|---|
| Move | Arrow keys | D-pad / left stick |
| A | Z | South button |
| B | X | East button |
| Option | Enter | Start |
| Quit | Esc |
The game runs at its own rate (about 59.95 frames a second, with the scenery and sprites stepping every second frame) and each refresh of the monitor shows a picture drawn between the game's frames, so motion follows the monitor's refresh rate. Sound is kept in time by nudging the clock by a fraction of a percent.
--aspect 16:9|16:10|original picks the shape of the picture (--widescreen
is 16:9, the default); Tab or F10 cycles through them while playing and the last choice is
remembered. In a level a wide view shows the level itself beyond the original
screen's edges, read from the cartridge, with the HUD at the edges; every other
screen (title, menus, special stages) is the original 160x152 centred with
black bars. The game is told to keep the sprites and objects of the extra
width (it normally drops anything off the 160-pixel screen), so a platform or
an enemy is there as the wide picture reaches it. The zone's title card is
centred over the level, which is already where it will be, and so is the act clear (the
"Sonic got through" screen), wherever the camera has stopped. Where the camera is
locked at the end of an act 1 and in the boss arenas (every zone's boss but the
third's, which has no lock, and the last fight), the level is shown beyond the
screen instead of black bars and the player may walk to the edges of the picture,
on a floor the wide view fills in where the level's data stops short (the last 64
pixels of the level, never seen before; where an arena's last wall ends before the
data does, the wall's last column of tiles is repeated); the first zone's boss goes
the whole width. The third zone's boss is as it was. The fifth zone's flight shows its
plane once (it is a picture the game slides, which wrapped round into the extra width),
its two flapping bird robots start beyond the picture and fly in, and at its end the
level's last 64 pixels are shown, so the view is as centred there as in any other act. The
last fight's machine is drawn by the game one half at a time, the half on the screen, so the
game is told to draw the half in the wide view's margin too. When the machine is beaten his pod
comes out, and the player has to hit it to end the level: the explosions and the pod's approach are
wide, but from that second hit through the act clear, the walk across the level, the fade and the
endings and the credits, which are made for 160 pixels, the picture is centred between black bars
like the other screens. The last bonus level, Chaotic Space (the level select's last entry), has no level
behind its picture, only the planet and the stars, two pictures of 256 pixels that the game slides round, so a
wide view draws them all the way round (a 16:9 view sees the first 14 columns again at its far end, which
is not noticed in a sky, but is in Robotnik's machine: its body is a block of the front picture that the game
moves by sliding the picture, so it is drawn once, in the lap of the ring where the machine is, and not again
at the far side) and Super Sonic may fly to the edges of the picture; the fight is wide from its title card to the end of the
machine's defeat, and the act clear and the scenes after it, made for 160 pixels, are centred between black
bars as the last fight's end is. Those are
the things a wide view does to the game itself: objects wake up a little
earlier, the player and the first boss get more room, the last boss's machine is drawn whole, and the longer sprite
list can move the game's tick by a frame, so a recording made in one aspect plays
back exactly only in that aspect. A wide view also eases the vertical camera, which
the game starts and stops abruptly (the horizontal one follows Sonic's speed): the
level and the sprites move together, up to 12 pixels from where the game has them,
and the game keeps the sprites of that margin above and below the screen as it does
those at the sides. The pause banner (Option) goes across the whole width of the picture, over the level.
--refresh auto|60|90|120 (F6 steps through 60, 90 and 120 while playing; the choice is remembered, and
60 is the default) sets how many pictures a second are shown. auto (command line only) shows one for
every refresh of the display, whatever its rate.
60 is one for each of the game's own frames (the scenery steps every second frame, so the other is
half way), 90 is three for every game step and 120 is four. The rate suits a display that runs at that
rate or a multiple of it: on a 120 Hz display 60 repeats each picture for two refreshes, 120 is a new
picture every refresh, and 90 is shown for one refresh or two alternately, so it is uneven there; a
display slower than the rate asked for simply shows every refresh. Every picture between the game's
steps places the level and the sprites to a quarter of a pixel, so a fast scroll moves evenly at any of
these rates and not by a different whole number of pixels from one refresh to the next (--no-subpixel
puts them back on whole pixels, to compare).
The picture is fitted to the window by --scale-mode: sharp (the default; F8 cycles
the modes and the choice is remembered) fills the window with evenly wide pixels at any
size, integer uses whole multiples with bars (270 x 7 = 1890 pixels at 1080p), and
nearest is plain scaling, which gives pixels of two different widths unless the window
happens to be a whole multiple. The game opens in borderless fullscreen, and F11 or Alt+Enter
switches between that and a window (--windowed opens in a window; --window and --screenshot
do too, and --fullscreen overrides them; it is not remembered). The window
is made with a high pixel density, so a Retina display is drawn in its own pixels and not
scaled up (and softened) by the system. The sound is kept --audio-latency frames deep
(default 2, about 36 ms; it raises itself by a frame if the device runs dry), where it was
4 (about 67 ms). --frame-delay (auto, off or milliseconds) waits before reading the
buttons so that they are read late in the refresh; auto does this only where a refresh is
12 ms or longer (60 Hz) and is off on a faster display, where there is little to gain.
--stats reports how long a key press takes to reach a presented picture and how deep the
sound queue was. --window WIDTHxHEIGHT sets the window's size, and --screenshot file.png [--screenshot-at FRAME] writes the window's picture (in the display's pixels) and quits.
The three choices above are also rows of the game's own Game Option screen (title menu, Go To Room,
Game Option), under Difficulty, Time Out and Player: Drop Dash (on or off), Frame Rate (60, 90 or 120
Hz) and Aspect (16:9, 16:10 or Original), with Sound Test and Special Stage between Drop Dash and
Frame Rate once they are unlocked. They take the place of Auto Power Off, which did nothing here, and of
Exit (B leaves, as it did). Left and Right (or A) change a row; a change is applied at once and remembered
like the hotkeys', and the hotkeys change the rows. The rows are the host's, not the game's: they are not
in the save. How the screen is taken over is in docs/notes/options-screen.md.
ngpc-run and spa-verify leave the screen as the game has it unless given --option-screen.
--drop-dash (or F7 while playing, which is remembered; --no-drop-dash turns it off for
a run) gives Sonic the drop dash of Sonic Mania, a move the game does not have, so it is off
unless asked for. Jump, press a jump button again in the air and keep it held: after about a
third of a second the spindash's rev sounds and he is charged (letting go before landing cancels
it); from the press he spins as the solid blue ball, not the frames that show his shoes and eyes.
Landing with the button still held starts a roll at once, at a quarter of the speed he
came in with plus the spindash's weakest launch speed (half of it if he lands going backwards),
up to its strongest. It works through hooks on the player's code and reaches the game's own
state, so with it on a recording replays exactly only with it on; with it off nothing changes. (A
recording made while using the Game Option screen's rows replays exactly only with ngpc-run --option-screen, and one made in the window now defaults to 16:9, so ngpc-run needs --aspect 16:9.)
ngpc-run and spa-verify take --drop-dash as well (spa-verify --input buttons.txt --drop-dash checks that recompiled and interpreted play stay in lockstep through a dash, and
--option-screen through a visit to the Game Option screen).
Options: --scale N (window size, default 4), --japanese,
--no-smoothing (show only the game's own frames),
--fps N (present N pictures a second by the clock instead of waiting for the
monitor), --stats (print how evenly pictures were presented, and how evenly the
game's clock stepped, when the window closes; --quit-after SECONDS closes it for you), and
--interpreter to run the same game on the interpreter instead of the
recompiled code. --record input.txt logs every frame's buttons from a fresh
cartridge (the save file is untouched), --replay input.txt plays such a log
back in the window, and F9 bookmarks the frame on screen;
ngpc-run --rom <cartridge> --input input.txt --bookmarks input.txt.bookmarks
then replays the session headlessly and writes a contact sheet of the real and
in-between pictures around each bookmark. Save data is stored in the SDL preferences folder
(%APPDATA%\SonicPocket\SonicPocket\flash_save.bin on Windows,
~/Library/Application Support/SonicPocket/SonicPocket/ on macOS,
~/.local/share/SonicPocket/SonicPocket/ on Linux).
Gamepads
Any pad that SDL3 recognises works on Windows, macOS and Linux, and can be plugged in before or during play. The first pad found is used; if it is unplugged, the next one connected takes over. The name of the pad in use is printed when it is opened.
- A pad that SDL has no mapping for is ignored (nothing is printed). Give it one with
an SDL controller mapping string in the
SDL_GAMECONTROLLERCONFIGenvironment variable, or put agamecontrollerdb.txt(the community database) next to the executable or in the folder that holds the save data. The game prints how many mappings it read from each file. - Linux: you need read access to
/dev/input/event*(a normal desktop login has it; otherwise join theinputgroup). PlayStation and Switch Pro pads read through HIDAPI also need udev rules for/dev/hidraw*, which Steam and most distributions install. - Input from a pad is only delivered while the game's window has focus.
Verifying
cmake --build build/recomp --config Release --target spa-verify -- /m:1
build\recomp\Release\spa-verify.exe --rom "path\to\cartridge.ngc" --frames 1200
To compare the machine against BizHawk, capture a reference with
scripts/bizhawk-dump-reference.lua (see its header), dump the same frames with
ngpc-run --dump-ram, and run tools/compare_ram_frames.py.
Repository policy
This repository contains no ROM data, extracted assets, BIOS or generated code. The recompiled C++ is produced at build time from your own cartridge. Committed files are o