DX-Ball reconstruction

This project reconstructs English DX-Ball v1.07 as readable C/C++ using the original executable and resources. Codex uses REA to inspect the program through Ghidra, recover its functions, and compare code compiled with Visual C++ 4.0 against the original.

▶ Watch the Windows build & gameplay demo
_{6:20 · Compilation at 4× speed · Gameplay at normal speed}

All 270/270 authored game functions and 84,968/84,968 authored code bytes are exact. Source recovery completed on October 22, 2026; the October 31 update adds native Windows build verification and windowed play results. The game builds from the reconstructed C/C++ with the original VC4 compiler.

The current game has these recorded results:

Remaining validation:

• Complete the original 50-board campaign and exercise every power-up in live play.
• Resolve exclusive-mode focus/surface recovery under Wine/Xvfb. The windowed wrapper uses different activation behavior.
• Complete native graphics/audio/MIDI and frame-pacing coverage. Manual feedback is scoped separately from automated checks.

See progress, the build record and playability results for counts and evidence.

1. Inspect a function's instructions, pseudocode, calls and data references.
2. Recover its logic in typed C/C++ and connect it to the game.
3. Compile with VC4 and compare the complete function, then use remaining differences to refine types, state writes, control flow and source layout.

Comparisons map relocated calls and data references to their original addresses and include literals and attached metadata. The projectile-list example follows one routine from analysis to an exact compiler match. The matching guide describes the records and comparison commands.

Prepare the workspace using the setup guide. Then import the original game archive and build the restored-CRT profile:

scripts/bootstrap-python.sh
scripts/repo-python scripts/import-target.py /path/to/DX_Ball_Win_Preinstalled_EN.zip
scripts/repo-python scripts/bootstrap-tools.py
scripts/repo-python scripts/build-legacy.py --restored-crt
scripts/repo-python scripts/run-windows.py --profile vc40-restored-crt

The build links 138 source objects, three integration objects and 19 original CRT members. Original assets are supplied separately. The build guide covers headless Wine, other build profiles and the local delivery bundle.

The Windows build shown in the video uses an exported source package with reconstruction/src/, the pinned VC4 compiler/headers/libraries, support files and reconstruction/build-plan.json. Windows PowerShell 5.1 and x86 application support are sufficient; Python, WSL and Visual Studio are not needed on the Windows machine.

Prepare the package on Linux/WSL after the restored-CRT build above. Choose a new package directory. Obtain ddraw.dll and ddraw.ini configured for the tested cnc-ddraw windowed profile, then run from the repository root:

scripts/repo-python scripts/run-windows.py \
  --profile vc40-restored-crt --prepare-only
mkdir -p build/windows-source-package/game
cp -a build/runtime/vc40-restored-crt/. build/windows-source-package/game/
cp /absolute/path/to/cnc-ddraw/ddraw.dll \
  /absolute/path/to/cnc-ddraw/ddraw.ini build/windows-source-package/game/
scripts/repo-python scripts/export-windows-build.py \
  build/windows-source-package/reconstruction

The exporter requires the completed Linux build and pinned local toolchain; reconstruction/ must not already exist. It generates the Windows launchers and build plan. The .ps1 file alone is not a complete build package.

Build and play on Windows:

1. Copy the entire build/windows-source-package/ folder to Windows. Keep its game/, reconstruction/ and generated .cmd files together.
2. Open Build Reconstruction.cmd in the package root. It verifies the supplied inputs, compiles all 141 C/C++ units with English percentage progress, extracts the 19 approved original CRT members, and links the EXE. The required linker compatibility setting is applied automatically.
3. Wait for BUILD COMPLETE. The new executable is build/game/dxball.exe; compiler output is in build/logs/ and the receipt is build/build-report.json, all relative to the package root.
4. Open Play Rebuilt DX-Ball.cmd to play the newly compiled game. Building does not launch it; the existing game/ copy and rebuilt score saves are preserved.

The normal launcher compiles every source unit. An optional incremental build can be run from the package root in PowerShell:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\reconstruction\Build-Reconstruction.ps1 -Incremental

-Incremental reuses objects only when their compiler/source/header/flag context and hashes match. See native Windows build details.

This reconstruction was built with AI coding agents. Testing, recovered semantics, readability and platform support can still improve. Feedback, bug reports and contributions are welcome.

• Testing and bug reports. We have not tested every board, power-up or system configuration. Help test the original 50-board campaign, windowed and fullscreen behavior, audio/MIDI, frame pacing, and score/editor save flows. Report issues with your commit or build, OS, Wine/DirectDraw wrapper if used, reproduction steps, and expected versus actual behavior. Screenshots, videos and logs help.
• Ports. Help bring the shared C/C++ core to more platforms and architectures, or develop rendering, audio and input backends. Keep platform changes separate from the verified VC4 reconstruction.
• Semantics and readable code. Review reconstructed behavior, improve names and types, simplify control flow, and clarify comments or documentation. Focused fixes with a reproducible example or relevant regression check are welcome.

Send pull requests to main. Changes to recovered game code should preserve the accepted VC4 matches and include the relevant verification; see the contributor workflow.

• Architecture: entry, modes, a gameplay frame and platform services.
• Source map: the modules and compiler owners behind each subsystem.
• Research notes: source decisions and recorded experiments.
• Contributor handoff: current artifacts and the next verification work.
• Codex setup: tools, REA connection and a reconstruction workflow.

DX-Ball was created by Michael P. Welch, with 3D graphics by Seumas McNally. See LICENSE.