0.3.5 - ROM import and startup recovery

Fixes ROM installation and startup recovery for Issue #4.

• Install once on Windows: dragging a verified ROM onto the executable now saves an installed copy. Later launches work even if the original file is moved or removed.
• Recover older installations: an unrecognised ROM installed by an older version returns to setup, where Browse lets you select the correct image.
• Keep a working installation intact: unverified ROMs are rejected before replacing the installed copy. Errors show the selected path and actual/expected SHA-1 when the file can be hashed.
• Browse, window drag-and-drop, and command-line imports use the same SDL stream-based validation, including Android document URIs.

Validation: 95 unit tests and all 14 non-long CTest cases passed, including five startup regressions. Windows Browse recovery and restart after removing the source ROM were also verified through the UI. The packaged Windows build passed the startup tests with a system-only PATH.

Windows x64 and Android arm64-v8a/x86_64 builds are included. Android uses version code 8 and the same signing certificate as 0.3.4 for in-place updates. As with previous releases, the APK is debug-signed with Release native code; these changes have not been tested on Android hardware.

You must supply your own Knuckles' Chaotix (Japan, USA) ROM. No ROM image or game assets are included. Details: ROM import verification.

0.3.4 - Audio fixes

Two audio fixes for Windows and Android:

• 32X PWM stereo: normal stereo now plays the left and right PWM sources
  independently. Previously, both outputs used the left source. Swapped
  stereo now exchanges the sources correctly.
• YM2612 FM synthesis: algorithms 0, 1, 2, 3, and 5 now retain the
  previous sample's intermediate modulation result, correcting a missing
  delay that affected their sound. Other algorithms and output gain are
  unchanged.

These are targeted fixes, not a claim of fully hardware-accurate audio.
Further work on FM accuracy and mixing remains.

Validation: 92 unit tests and all 13 non-long CTest cases passed. A separate
3,600-frame run with audio enabled passed the existing execution checks,
and the final FM output matched the validated experiment across 3,200,142
stereo sample pairs. Windows and both Android architectures build
successfully; the audio changes have not yet been tested on Android hardware.

The Android APK includes arm64-v8a and x86_64, uses version code 7, and keeps
the same signing certificate as 0.3.3 for in-place updates.

Details: PWM fix,
FM fix,
and FM investigation.

Includes the frame-pacing improvements from 0.3.3 and Android ROM import fix
from 0.3.2. You must supply your own ROM; no ROM or game data is included.

0.3.3 - Frame pacing

A frame-pacing fix for smoother motion, while keeping the original game speed
of approximately 59.92 FPS.

The frontend could present an unchanged frame before the next game update was
due. With VSync enabled, that could leave the following presentation catching
up by two game frames. It now waits for the next game-frame deadline before
polling input. With VSync disabled, it also avoids repeatedly rendering the
same frame. Fast-forward, automated tests, and bounded recovery after a stall
remain supported.

In two Windows tests on a 60 Hz display, the 99th-percentile interval between
new-frame presentation returns improved from 33-34 ms to approximately 20 ms.
These are application-side measurements, not physical display latency or a
benchmark against PicoDrive. Details are in the
frame-pacing report.

Validation: 85 unit tests and all 13 regular CTest entries passed.
Windows gameplay, automated menu navigation, synthetic fast-forward, and
recovery from an injected two-second stall were checked. Both Android
architectures build successfully; this timing change has not been retested
on Android hardware.

The Android APK includes arm64-v8a and x86_64, keeps the same debug signing
certificate as 0.3.2, and uses version code 6 for in-place updates.

Includes the Android ROM import fix from
0.3.2.
As before, you must supply your own ROM. No ROM or game data is included.

0.3.2 - Android ROM import

A fix for choosing a ROM on Android, reported in
issue #2: Browse
opened the file picker, but selecting a valid ROM came back with
"cannot open ROM".

Android returns a content:// document URI from its file picker. The setup
screen was treating that as an ordinary filename, so it failed before it
could check the ROM. It now reads the document through SDL, stages it inside
the app's folder, and passes it through the existing ROM checks and installer.
Failed reads, invalid images and files larger than 8 MiB leave an existing
installation alone, and the temporary import file is removed afterwards.

The original failure and the fix were both checked on an AYANEO Pocket S2
Pro. Browse now installs the ROM and reaches the main menu, the installed
copy has the expected SHA-1, and restarting still works after the original
selected file is removed. Selecting an already installed ROM on Windows
also remains supported.

The Android download keeps the same signing certificate as 0.3.1 and includes
both arm64-v8a and x86_64. Its version code is now 5, so it can be installed
over the previous release. As before, it is debug-signed.

Everything else is as in
0.3.1,
including what these downloads contain and the ROM you still have to supply
yourself. No ROM or game assets are included.

0.3.1 - the time attack clock

A fix for the time attack clock, reported an hour after 0.3.0 went out: a run
of Techno Tower was recorded about seven seconds longer than the game itself
had shown.

Where a run's clock starts is not something the game keeps anywhere, so it was
being worked out from FFE052, which counts one per frame from the moment
play begins. It carries whatever the scene before left in it — that run came
into the level holding 77 — and the level only zeroes it part way through its
entry sequence, so the clock started 414 frames early. Waiting for the zero
first is not enough either: it blips to 1 for a single frame during the entry.

A reading now counts only after it has climbed by one on each of several
consecutive frames, and the earliest start any such reading implies is the one
kept — pressing something puts it back to zero, which can only imply a later
start, never an earlier one.

Both of the recorded runs there are to check against now read exactly what
their player saw: one ends at the 0'34"66 on its results screen, and the
other reads 0'05"01 mid-level where the game's own HUD reads 0'05"01.

Introduction keeps no clock worth reading — it is a tutorial — so a run there
ends without a time rather than with a time of zero, and nothing is recorded
for it.

Everything else is as in 0.3.0,
including what these downloads are and the ROM you still have to supply
yourself.

0.3.0 - a front end, and a time attack

A front end of its own, and a time attack built out of a stage-select screen
the shipped game never lets you reach.

You still need your own ROM

These downloads are not the game. They contain the game's code,
statically recompiled, and none of its data — no graphics, no music, no
level data, no ROM image. Start one without a ROM and it stops at the setup
screen.

You supply your own, legally obtained copy of Knuckles' Chaotix (Japan, USA)
for the Sega 32X, SHA-1 0c2fff7bc79ed26507c08ac47464c3af19f7ced7, which the
setup screen verifies before installing it.

The front end

The menu is up as soon as the program starts: the game's own title art framed
on the left, the list beside it — START GAME, TIME ATTACK, OPTIONS, CONTROLS,
AWARDS, QUIT — over the same picture enlarged and dimmed. The art is the game
drawing its own title screen, from your ROM, so nothing is extracted or
shipped here.

START GAME hands the game over exactly as pressing Start on the console would,
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 own title screen, so the front end keeps one.

TIME ATTACK

Knuckles' Chaotix carries a complete stage-select screen that the shipped game
never reaches: game mode 0x30, with PLACE, LEVEL, AT-TIME, PLAYER, COMBI and
PLAYERS. That is the whole of a time attack, so the page offers what it
offers, and starting a run uses the game's own route into a level.

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	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. Two players really
is two players: with it set, the partner reads the second controller, which
is worth knowing about a game that was sold as one-player.

START goes straight there in about a second — none of the game's own screens
are passed through — and BEST TIME shows the record for whatever is selected.
When a run ends the game would send you to its lobby; the front end takes the
time and brings you back to the page instead.

The clock stops where the game stops its own: at the goal, not at the end of
the twenty-odd seconds of tally afterwards. A record therefore reads the same
as the time you watched when you finished. That took three attempts to get
right, and the third one only worked because the program now records each run
and can replay it exactly.

Controls

Each player gets its own device — AUTO, the keyboard alone, one gamepad by
name, or nothing — and its own bindings, keyboard and gamepad kept separately,
so two people can share one keyboard or two controllers can be laid out
differently. Each row also says what that button does in this game: C jumps,
B holds your partner still, A pulls the partner in for ten rings, Start
pauses. X, Y, Z and Mode say NOT USED BY THIS GAME, because they are — this is
a three-button game, and pressing them changes neither the picture nor the
game's state, anywhere it was tried.

MENU BUTTON is Escape's counterpart on a controller, chosen from the buttons
the emulated 6-button pad leaves alone.

Achievements

Twenty-two now, 270 points: rings, each of the seven attractions, how far in
you get, one for each of the seven characters, and one for playing with a
second player on the partner. The character ones want TIME ATTACK, which is
how you reach a character the game would otherwise have chosen for you. Each
was checked by driving the game to it.

Notes

• The Android build is debug-signed. Release signing needs a keystore that
  belongs to whoever publishes it, so there is not one here.
• Linux and macOS are built in CI but have never been run on hardware, so
  there are no downloads for them.

Read LEGAL.md in the download before redistributing it. In short: the binary
holds a translation of Sega's code, it is inert without your own ROM, and the
legal standing of shipping it is not settled. This follows what other static
recompilation projects do — Unleashed
Recompiled and Zelda 64:
Recompiled ship the same kind
of build.

0.2.0 - the recompiled build

The recompiled build, which is what this project is for. v0.1.0 shipped the
interpreter; these downloads run the game's code translated ahead of time into
native code for your machine.

You still need your own ROM

These downloads are not the game. They contain the game's code,
statically recompiled, and none of its data — no graphics, no music, no
level data, no ROM image. Start one without a ROM and it stops at the setup
screen.

You supply your own, legally obtained copy of Knuckles' Chaotix (Japan, USA)
for the Sega 32X, SHA-1 0c2fff7bc79ed26507c08ac47464c3af19f7ced7, which the
setup screen verifies before installing it.

This follows what other static recompilation projects do — Unleashed
Recompiled and Zelda 64:
Recompiled ship the
recompiled code and require each user to bring their own copy of the game.
That position is not settled law, and
LEGAL.md
says so plainly rather than claiming otherwise. Read it before mirroring these
files anywhere.

Downloads

File	Notes
ChaotixRecompiled-0.2.0-windows-x64.zip	Windows 10/11 x64. Unzip anywhere and run ChaotixRecompiled.exe.
ChaotixRecompiled-0.2.0-android.apk	Android 8.0+ (arm64-v8a and x86_64). Signed with the standard Android debug key, so your device will warn about an unknown source. Copy your ROM to Android/data/org.chaotixrecompiled/files/, or use Browse on the setup page.

Built from the v0.2.0 tag on a local machine, because the build needs a ROM
and CI has none.

What works

• Boots to the title screen; menus, character select and the stage-select hall
• Levels are playable, with sound (Z80 driver, YM2612, PSG, PWM)
• True widescreen in levels: the game's own renderer is extended to draw
  real tiles, objects and sprites in the extra area rather than stretching a
  4:3 image. Anything from 1.24:1 (320×240) to 2:1 (480×224) is filled, and
  the centre 320 pixels stay bit-identical to the unmodified game — checked by
  a test.
• First-run setup that verifies your ROM by SHA-1 and installs it once
• 13 local achievements (no account, nothing downloaded); F7, left stick
  click on a gamepad, or the counter in the corner on a touch screen
• Windows, Linux, macOS, Android; gamepad, keyboard and touch

How it is validated

The recompiled code and the reference interpreter run in lockstep and must
agree exactly — every register, memory write and cycle count. The suite
includes two 36,000-frame lockstep runs and golden frame hashes for 4:3,
widescreen and 16:9. Where a translation would be unsafe, the runtime falls
back to the interpreter rather than guessing.

Known gaps

• Linux and macOS build in CI but have not been run on real hardware by the
  author, so there are no downloads for them yet
• iOS is configured but not yet built
• The Android APK is debug-signed; a properly signed release build needs a
  keystore, and the build now accepts one
• The level timer is not yet decoded, so there are no time-based achievements

0.1.0 - playable, widescreen, achievements

Superseded by v0.2.0,
which ships the recompiled build. This release predates that decision and
its notes below say a recompiled binary cannot be distributed; the project's
position changed in v0.2.0, and
LEGAL.md
now sets out the current one. The interpreter downloads here still work and
remain the more conservative option.

First tagged version: the game is playable end to end, with sound, true
widescreen in levels, a first-run setup page, local achievements, and builds
for Windows, Linux, macOS and Android.

Read this before downloading

The download below is not the game, and it is not the recompiled build.

It contains no game data at all — no ROM, no graphics, no music, not one byte
of Sega's program. You supply your own legally obtained copy of Knuckles'
Chaotix (Japan, USA) (SHA-1 0c2fff7bc79ed26507c08ac47464c3af19f7ced7), and
the setup page on first launch installs it.

It is also the interpreter build, not the statically recompiled one. The
point of this project is recompilation — translating the 68000 and SH-2 game
code into native C++ ahead of time — but that output is a translation of
Sega's copyrighted program, so a recompiled binary cannot be distributed. See
LEGAL.md.

The interpreter runs the same game from the same ROM and is what the
recompiled code is validated against frame by frame. It is roughly 3x slower,
which is still comfortably above real time on a modern machine.

To get the recompiled build, build it yourself with your ROM:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCHAOTIX_ROM=/path/to/chaotix.32x
cmake --build build

Downloads

File	Notes
ChaotixRecompiled-0.1.0-windows-x64.zip	Windows 10/11 x64. Unzip anywhere and run ChaotixRecompiled.exe.
ChaotixRecompiled-0.1.0-android.apk	Android 8.0+ (arm64-v8a and x86_64). Signed with the standard Android debug key and marked debuggable, so your device will warn you about installing from an unknown source. Copy your ROM to Android/data/org.chaotixrecompiled/files/ (or use Browse on the setup page).

Both are the interpreter build and contain no game data.

What works

• Boots to the title screen; menus, character select and the stage-select hall
• Levels are playable, with sound (Z80 driver, YM2612, PSG, PWM)
• True widescreen in levels: the game's own renderer is extended to draw
  real tiles, objects and sprites in the extra area rather than stretching a
  4:3 image. Anything from 1.24:1 (320×240) to 2:1 (480×224) is filled, and
  the centre 320 pixels stay bit-identical to the unmodified game — checked by
  a test.
• First-run setup page that verifies your ROM by SHA-1 and installs it once
• 13 local achievements (no account, nothing downloaded)
• Windows, Linux, macOS, Android; gamepad, keyboard and touch

How it is validated

The recompiled code and the reference interpreter run in lockstep and must
agree exactly — every register, memory write and cycle count. The suite
includes two 36,000-frame lockstep runs and golden frame hashes for 4:3,
widescreen and 16:9.

Known gaps

• Linux and macOS build in CI but have not been run on real hardware by the author
• iOS is configured but not yet built
• The level timer is not yet decoded, so there are no time-based achievements