Chaotix Recompiled

Chaotix Recompiled is a native C++ recompilation of the Sega 32X game Knuckles' Chaotix with true widescreen support.

README

Knuckles' Chaotix Recompiled

CI

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.

PlatformState
Windowsbuilt and played (MSYS2 GCC, and MSVC)
Linuxbuild configuration present, not yet run by the author
macOSbuilds and runs on Apple Silicon (an M1; every test passes, lockstep bit-identical)
Androidbuilds and runs (verified on an API 36 emulator); OPTIONS > VIDEO > SHOW FPS shows how fast it runs (performance notes)
iOS / iPadOSbuilds 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).

KeyAction
ArrowsD-pad
Z / X / CA / B / C
A / S / DX / Y / Z
EnterStart
EscMenu (on a pad, the button set under CONTROLS - left stick click to start with)
F1 / F5Debug overlay / overlay page
F2Aspect ratio (Auto, 4:3, 16:9, 16:10, 21:9)
F3 / F4Filter / scaling mode
F6True widescreen on/off (applies from the next level load; resizing the window applies at once)
F7Achievements (the menu's Awards page)
F11, Alt+EnterBorderless fullscreen
Tab (hold)Fast-forward (on a pad, the right trigger; see Fast-forward below)
F8 / F9Save state / load state, in the current slot (see Save states and rewind below)
F10Next save state slot (1-4)
Backspace (hold)Rewind (on a pad, the left trigger)
F12Screenshot
Home / EndStart / 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, MenuFont and MenuBackground in [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:

FieldWhat it chooses
PLACEBotanic Base, Speed Slider, Amazing Arena, Techno Tower, Marina Madness, Training, Introduction
LEVELwhich of that place's levels — the attractions have 1-5, Training 0-4
AT-TIMEMorning, Day, Sunset, Night
PLAYERthe character you play: Mighty, Knuckles, Charmy Bee, Vector, Bomb, Heavy or Espio
COMBIthe partner on the other end of the tether, from the same seven
PLAYERS1 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.bmp in Mods/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