Chaotix Recompiled
Chaotix Recompiled is a native C++ recompilation of the Sega 32X game Knuckles' Chaotix with true widescreen support.
- Type: PC port
- Game: Knuckles' Chaotix
- Runs on Windows, Linux, macOS, Android and iOS
- By YuutaTsubasa
- Latest release v0.15.22, 2026-11-15
- Source: https://github.com/YuutaTsubasa/ChaotixRecompiled
README
Knuckles' Chaotix Recompiled
A static recompilation of the Sega 32X game Knuckles' Chaotix into native C++. This is not an emulator: the 68000 and both SH-2 CPUs' game code is translated ahead of time into C++ that is compiled for the host. A small hardware compatibility layer (32X and Mega Drive registers, both VDPs, interrupts, timers, sound chips) plus an SDL3 frontend make it an ordinary native program on each platform.
How it was made, step by step, with the numbers behind each step: the Recompiled Handbook (English and Traditional Chinese; its source is site/index.html).
Much of it comes from the community's code, reports and ideas: see Credits for everyone who helped.
No game data is included. You supply your own legally obtained ROM of
Knuckles' Chaotix (Japan, USA) — SHA-1
0c2fff7bc79ed26507c08ac47464c3af19f7ced7. No 32X BIOS is needed. Read
LEGAL.md before building or sharing anything.
What works
Boots to the title screen; menus, character select and the stage-select hall work; the levels are playable, with sound (Z80 driver, YM2612, PSG and PWM).
True widescreen in levels: the game's own level renderer is extended to draw real tiles, objects and sprites in the extra area, rather than stretching or cropping a 4:3 image. Anything from 1.24:1 (320×240) to 2:1 (480×224) is filled — 426×224 at 16:9 — and the centre 320 pixels stay bit-identical to the unmodified game, which is checked by a test. The title screen's horizon fills the sides too (issue #77), and so does the rock behind DATA LOAD, TRAINING, PLAY STYLE and PLAYER SELECT (issue #135); other scenes outside levels stay 4:3.
| Platform | State |
|---|---|
| Windows | built and played (MSYS2 GCC, and MSVC) |
| Linux | build configuration present, not yet run by the author |
| macOS | builds and runs on Apple Silicon (an M1; every test passes, lockstep bit-identical) |
| Android | builds and runs (verified on an API 36 emulator); OPTIONS > VIDEO > SHOW FPS shows how fast it runs (performance notes) |
| iOS / iPadOS | builds and runs in the iOS Simulator; an .ipa for sideloading, not yet tried on a device |
docs/MILESTONES.md tracks the detail; ARCHITECTURE.md explains how it is put together. (Those two documents are written in Traditional Chinese; the rest of the documentation is in English.)
Build
Requirements: CMake ≥ 3.20, a C++17 compiler, and SDL3 plus SDL_ttf for the playable frontend. GCC, Clang and MSVC all build the tree warning-free.
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCHAOTIX_ROM=/path/to/chaotix.32x
cmake --build build
The build runs chaotix_recomp over your ROM (guided by the execution traces
in coverage/) and compiles the resulting C++ from generated/. Without
CHAOTIX_ROM you get an interpreter-only runtime and the unit tests — which
is what CI builds, since CI has no ROM.
Windows (MSYS2 MinGW64): pacman -S mingw-w64-x86_64-{gcc,cmake,ninja,sdl3,sdl3-ttf},
and pass a Windows-style ROM path (cygpath -m).
Where SDL is not packaged (Android, iOS, CI), point the build at source
checkouts instead: -DCHAOTIX_SDL3_SOURCE_DIR=... and
-DCHAOTIX_SDL3_TTF_SOURCE_DIR=... (the latter needs its vendored
submodules, so clone it with --recurse-submodules).
Presets: cmake --preset windows-msvc | windows-ninja | linux | macos-universal | macos-xcode | ios | android-arm64, with the CHAOTIX_ROM
environment variable set.
Cross builds (Android, iOS) do not run the recompiler: build once on a host
with CHAOTIX_ROM so generated/ exists, then configure the target build,
which picks it up. See platforms/android/README.md,
and docs/BUILDING_APPLE.md for the macOS app and the
iOS .ipa (scripts/package_apple.sh macos|ios VERSION on a Mac).
Run
build/ChaotixRecompiled
On the first launch a setup page asks for your ROM. It lists the ROMs it can
find (Downloads, Documents, an __ROM__ folder next to the executable, the
app's own folder on Android, the app's Documents on iOS, where the Files app
can put it); you can also drag a file onto the window, press
O to browse, or tap the on-screen buttons. The file is verified by SHA-1 and
copied into the app's own folder, so later launches go straight into the game.
A verified ROM given on the command line (including dragging it onto the
Windows executable) replaces the installed copy, so later launches do not need
the original file. Unrecognised images are rejected without replacing an existing
installation; the error shows the selected path and both SHA-1 values. If an
older version installed an unrecognised image, startup returns to setup so you
can choose a verified ROM with Browse.
Useful flags: --user-dir DIR keeps settings, saves and the installed ROM in
DIR (a portable install), --install FILE installs a ROM without showing
the setup page (for packaging scripts), and --menu main|options|awards
opens a menu page at startup (so it can be captured without a keyboard;
timeattack is one of them).
Settings live in the user data directory (Config/chaotix.ini), saves in
SaveData/, the installed ROM in Game/. That directory is
%APPDATA%\ChaotixRecompiled\ChaotixRecompiled on Windows,
~/.local/share/ChaotixRecompiled/ChaotixRecompiled on Linux,
~/Library/Application Support/ChaotixRecompiled/ChaotixRecompiled on macOS
and the app's Documents on iOS (the Files app's On My iPhone > Chaotix).
| Key | Action |
|---|---|
| Arrows | D-pad |
| Z / X / C | A / B / C |
| A / S / D | X / Y / Z |
| Enter | Start |
| Esc | Menu (on a pad, the button set under CONTROLS - left stick click to start with) |
| F1 / F5 | Debug overlay / overlay page |
| F2 | Aspect ratio (Auto, 4:3, 16:9, 16:10, 21:9) |
| F3 / F4 | Filter / scaling mode |
| F6 | True widescreen on/off (applies from the next level load; resizing the window applies at once) |
| F7 | Achievements (the menu's Awards page) |
| F11, Alt+Enter | Borderless fullscreen |
| Tab (hold) | Fast-forward (on a pad, the right trigger; see Fast-forward below) |
| F8 / F9 | Save state / load state, in the current slot (see Save states and rewind below) |
| F10 | Next save state slot (1-4) |
| Backspace (hold) | Rewind (on a pad, the left trigger) |
| F12 | Screenshot |
| Home / End | Start / reset a speedrun timer run (see Speedrun tools below) |
The menu is the front end: it is up as soon as the program starts, drawn on the game's own title screen, which fills the window as the game does in play. The entries — START GAME, TIME ATTACK, LEVEL SELECT, OPTIONS, CONTROLS, MUSIC PLAYER, AWARDS, NETPLAY, QUIT — step through the box where the title shows PUSH START, the chosen one on a purple plaque between two spinning rings (the game's own, from your ROM; issue #134), the others under it (on a portrait screen, under the picture) (issue #3; docs/MENU_ART.md). The title is the game drawing its own screen, from your ROM, so nothing is extracted or shipped. While the menu is open the title stays, music and all, rather than giving way to the attract demo; before PUSH START is up (the intro) only a hint shows, and the first press skips to the title.
OPTIONS is split into VIDEO (widescreen, aspect ratio, scaling, screen, menu size), SOUND (the volumes), INPUT (touch controls, fast-forward, 6-button pad), EXTRAS (cheats, lobby shortcuts, the menu's look, awards, the new version check, and MODS, the mod packs) and GAMEPLAY (the ring tether).
New versions (issue #90): at start the program asks GitHub once for this
project's latest release, on a thread of its own, so a slow or missing network
never holds up the game. If a newer version is out, a notice says so on the
title screen and NEW VERSION 0.x.y appears under START GAME; picking it opens
that release's page with the downloads. Nothing about you or your game is
sent, just the one request. It does not download or install anything itself;
on Android the system always asks before an APK is installed, and the iOS build
is installed by hand. OPTIONS > EXTRAS > CHECK FOR UPDATES (CheckForUpdates
in [Game]) turns it off; the change takes effect at the next start.
The menu is written in the game's own font -- the white digits and shaded
yellow capitals of its TRAINING and DATA LOAD screens -- and shows the game's
zones behind itself, a different one each time it opens, under a translucent
coat of that zone's colour. Both are made from your ROM: the font is read
from it at start-up, and each zone's picture is rendered once by the game
itself, on a second machine in the background while a menu is open -- it is
paused whenever you are playing -- (a couple of seconds each on a PC, longer
on a phone), then kept in the user data folder under
Cache/Backdrops. Until a picture exists the menu is plain. OPTIONS > EXTRAS
MENU BACKGROUND picks CYCLE (every zone in turn, the default), one zone for good (WORLD ENTRANCE, ISOLATED ISLAND, BOTANIC BASE, MARINA MADNESS, SPEED SLIDER, AMAZING ARENA or TECHNO TOWER; only that picture is made), or PLAIN. MENU FONT (GAME / PIXEL) and MENU BACKGROUND on PLAIN,
MenuFontandMenuBackgroundin[Video], bring back the earlier look. How it works: docs/MENU_ART.md.
OPTIONS > VIDEO > MENU SIZE makes the menu's rows, letters and panels -- and
so the area a finger can tap -- larger: NORMAL, LARGE (half as large again)
or EXTRA LARGE (twice NORMAL). AUTO, the default, is LARGE on phones and
tablets, where a landscape screen is only a few centimetres tall and
NORMAL's rows come out a few millimetres high, and NORMAL elsewhere. The
letters stay on whole pixels: each size takes the game's font up by at least
a whole step. A page with more rows than fit shows a window of them that
follows the selection, with a marker where there are more; the pause menu's
row carries on onto a second line instead of running off the screen. It is
MenuSize (Auto, Normal, Large, ExtraLarge) in [Video].
START GAME hands the game control, and it proceeds into its own menus exactly as it would have on the console, so nothing the original offers is out of reach. Escape (or the pad's menu button) then brings up a pause menu, which adds BACK TO TITLE. The game has no way back to its title screen, so the title is copied when control is handed over and put back on the way out; anything chosen inside the game's menus is discarded, as it would be by turning the console off. The save is kept, as the cartridge's battery keeps it: progress the game has saved to a DATA slot is there when you come back. Progress made with NO SAVE (DATA LOAD's first choice, and the one selected at first) only ever lives in memory, so going back to the title loses it, as resetting the console would.
TIME ATTACK drops you straight into any level. Knuckles' Chaotix carries a complete stage-select screen that the shipped game never reaches (game mode 0x30), and the page offers exactly what that screen does, in its order:
| Field | What it chooses |
|---|---|
| PLACE | Botanic Base, Speed Slider, Amazing Arena, Techno Tower, Marina Madness, Training, Introduction |
| LEVEL | which of that place's levels — the attractions have 1-5, Training 0-4 |
| AT-TIME | Morning, Day, Sunset, Night |
| PLAYER | the character you play: Mighty, Knuckles, Charmy Bee, Vector, Bomb, Heavy or Espio |
| COMBI | the partner on the other end of the tether, from the same seven |
| PLAYERS | 1 PLAYER, or 2 PLAYERS to give the partner to the second controller |
The names, the levels each place has, and the two-player switch are all read out of the game's own tables rather than invented here, and START uses the game's own route into a level, so a run behaves exactly as the console would. START goes straight there, in about a second: none of the game's own screens are passed through, only its level entry (the ball wipe and the BOTANIC BASE ticket). A run is played with NO SAVE, as the stage-select screen sets it, so it never touches your DATA slots.
Every run is recorded, frame by frame, to SaveData/last_run.txt, and
chaotix_headless --replay-input plays one back exactly. It is there because
what the game does when a level is finished at the goal is not something a
script can reach, so the only way to study it is to record somebody reaching
it. A whole run is about 150 KB and holds nothing but pad readings.
BEST TIME shows the record for whichever stage is selected. When a run ends the game would send you to its lobby, so the front end takes the time and brings you back to this page instead, with what you managed. A run that used up the level's own ten minutes is not a time. The clock stops where the game stops it -- at the goal, not at the end of the twenty-odd seconds of tally afterwards -- so a record reads the same as the time you watched when you finished. Two players needs a device for player 2 under CONTROLS, which starts as NONE.
GHOST races a translucent copy of a run you made before: BEST (the stage's
fastest kept, whoever ran it), LAST (the stage's last finished run) or OFF.
Every finished run without cheats is kept, as a small file in Ghosts/ in
the user data folder, and on the next START of the stage the ghost's
characters run alongside you, half see-through and tinted, from the moment
the clock starts until the ghost reaches the goal, when its time is shown.
The game is deterministic, so the ghost is the recorded run's pads replayed
on a second machine from the moment the stage started; it never changes your
run. Copy the files to export or import ghosts. It starts as BEST on
computers, where it costs no frame rate, and OFF on phones, which may not
have the time for a second game. See docs/GHOSTS.md.
LEVEL SELECT starts any level the same way, as practice: no clock, no record,
no ghost, no speedrun split, and no awards, and save states, rewind and
fast-forward all work. Beside TIME ATTACK's places it offers WORLD ENTRANCE
(the lobby with all five attractions open), the six SPECIAL STAGEs and the
BONUS STAGE, with the same AT-TIME, PLAYER, COMBI and PLAYERS. It is NO SAVE
too, so finishing a level writes nothing to your DATA slots. When the level
is over -- the game sends you to its lobby, or a special stage ends -- you are
brought back to the LEVEL SELECT page; in WORLD ENTRANCE you play on until
you go BACK TO TITLE. Loading a save state from story mode (one with a DATA
slot) during it lets that game go on as it was. With 1 PLAYER, in the five
attractions, PARTNER also offers NONE: the level is played alone, as with
GAMEPLAY > PARTNER SOLO (below), for that level only. The choice is kept
apart from TIME ATTACK's, in [LevelSelect]. See
docs/LEVEL_SELECT.md.
CONTROLS gives each player a device of its own: AUTO (the keyboard and any gamepad, which is the default for player 1), the keyboard alone, one gamepad by name, or nothing. Each player has its own keyboard set and its own gamepad set, so two people can share one keyboard (player 2 starts on the keypad) or two controllers can be laid out differently. Choose a button and press Enter, then press the key or the gamepad button to bind it; Escape leaves it alone. Each row also says what that button does in this game: C jumps, B holds your partner still (the game answers with its own HOLD! bubble), A pulls the partner in for ten rings, Start pauses. X, Y, Z and Mode say NOT USED BY THIS GAME, because they are: pressing them changes neither the picture nor the game's state, on the title screen or in a level. The triggers can be bound too (pressed past half way), for 6-button pads such as the 8BitDo M30 and Retro-Bit's, which report C and Z as the right and left triggers. Fast-forward and rewind start on the triggers, so binding a game button to one sets that function's pad button to NONE (choose another under FAST FORWARD PAD or STATES AND REWIND); one input never does two jobs.
MENU BUTTON is Escape's counterpart on a controller: the emulated 6-button pad takes every face and shoulder button, so the choice is among the ones it leaves alone - left stick click (the default), right stick click, Guide/Home/PS, the touchpad click, or Share/Capture. The same button backs out of the menu again.
Fast-forward
FAST FORWARD KEY (Tab to begin with; press Enter, then the key) and FAST FORWARD PAD (the right trigger to begin with; also the left trigger, either stick click, Guide/Home/PS, the touchpad click, Share/Capture or NONE -- never one the emulated pad uses or a game button is bound to, nor the MENU BUTTON) are on the CONTROLS page. OPTIONS > INPUT has the rest:
- TOUCH FAST FORWARD (OFF by default) adds a small fast-forward button to the
touch controls, in the top-left corner, which both touch layouts leave
empty. Its image is
ff.bmpinMods/Touch. - FAST FORWARD: HOLD (on while held, the default) or TOGGLE (each press turns it on or off; the touch button stays lit while it is on).
- FAST FORWARD SPEED: 2X and 4X run exactly two or four frames of the game for every frame at the normal pace, and keep the sound -- all of it, played that many times faster, so it is higher but unbroken. MAX (the default, and what Tab always did) runs as fast as the machine allows, up to eight frames for every picture shown, and is silent because it has no steady speed to play the sound at.
Fast-forward only runs more frames of the same game, so the game behaves
exactly as it would have. It does nothing during a TIME ATTACK run (the touch
button is not shown either), so every record is set at the game's own speed,
nor while the menu is open. In the settings file: FastForwardKey,
FastForwardButton, TouchFastForward, FastForwardMode (Hold | Toggle)
and FastForwardSpeed (2x | 4x | Max) in [Input].
Save states and rewind
The pause menu's STATES page saves and loads the game in one of four slots
(SLOT), and turns rewind on or off. F8 saves, F9 loads and F10 picks the next
slot; holding Backspace (or the left trigger) steps back through the last
minute of play, at twice the game's speed and without sound, and letting go
plays on from there. CONTROLS > STATES AND REWIND rebinds the keys, gives
saving and loading a pad button if wanted (none to begin with) and turns on
an on-screen rewind button (TOUCH REWIND, off to begin with; rew.bmp in
Mods/Touch). Rewind is on to begin with on computers and off on phones and
tablets.
A state is the whole machine, so loading one carries on exactly as the game
would have from that moment; the cartridge save (the DATA slots) is never put
back by a load or by rewinding. States are files in States/ in the user data
folder and survive restarting the program, but only load with the same ROM,
ROM patches and version of this program. None of it works during a TIME
ATTACK run, so a record is always one unbroken run. See
docs/SAVE_STATES.md.
OPTIONS > EXTRAS has RESET AWARDS, which asks twice before locking everything again.
On-screen touch controls appear once the screen is touched (TouchControls = Auto), always (On), or never (Off). Gamepads work through SDL
(Xbox, PlayStation and Nintendo layouts): West/South/East = A/B/C,
LB/North/RB = X/Y/Z, Back = Mode (the game itself only uses three of those --
see CONTROLS). Every other button belongs to the emulated
6-button pad, so the menu is on one of the spare buttons (see MENU BUTTON
above); East/B backs out of it too. On touch devices virtual controls appear
over the game, with a menu button (three bars) in the top-left corner that
opens