DX-Ball reconstruction

This project reconstructs English DX-Ball v1.07 as readable C/C++ that can be compiled into a working game. Codex uses REA to inspect the original executable through Ghidra, recover its functions, and refine the source by comparing compiled code with the original.

REA gives Codex access to Ghidra's pseudocode, instructions, calls, and data references. The reconstruction proceeds function by function:

1. Inspect a function with REA. Read its pseudocode and instructions, then follow calls and data references to understand its logic and field layouts.
2. Recover the source. Express that logic in typed C/C++ and connect it to the rest of the game.
3. Compile and compare. Build with Visual C++ 4.0 and compare the whole function with the original. Use each difference to decide what to inspect or change next. A focused behavior check can resolve questions left by the code comparison.

A byte-exact match means the entire function's machine code agrees after mapping addresses for calls and data. The original and rebuilt programs place functions and globals at different addresses, so those references need an explicit mapping. The remaining bytes help resolve argument widths, branch conditions, and the order of state changes that pseudocode alone can miss.

Saved REA responses link source decisions to the executable. The worked example follows a projectile-list routine from analysis to source and a complete compiler match.

These steps set up a Linux x86-64 workspace and let Codex continue the reconstruction from the source and research in this repository. You will need:

• Git and Python 3.11+ with pip.
• Node.js 22.19.0 with npm. Use the official Linux x64 binary; the project checks the Node executable's hash as well as its version.
• Wine with 32-bit support, Xvfb with xvfb-run, unzip, and tar. Wine runs the original-era Windows compiler on Linux.
• CMake, Ninja, and GCC or Clang to build the portable source.

The setup scripts below download the JDK, Ghidra, and Visual C++ 4.0 compiler.

If you need the matching Node version, download node-v22.19.0-linux-x64.tar.gz and extract it into a directory you own. For example, with the archive in your Downloads directory:

mkdir -p "$HOME/.local/opt"
tar -xzf "$HOME/Downloads/node-v22.19.0-linux-x64.tar.gz" -C "$HOME/.local/opt"
export PATH="$HOME/.local/opt/node-v22.19.0-linux-x64/bin:$PATH"
node --version
npm --version

node --version should print v22.19.0. Keep using this terminal for the remaining steps. Add the export PATH line to your shell configuration if you want it available in future terminals.

Download the English Windows archive from DX-Ball on Old Games Download. Choose DX_Ball_Win_Preinstalled_EN.zip under Windows (1996). The original English readme identifies version 1.07 and describes the game and its controls. Keep the ZIP intact; the importer extracts the executable and assets together.

Fork this repository on GitHub so Codex can push its work to your copy. Replace YOUR_GITHUB_USERNAME with your username. Configure Git authentication for your fork before starting Codex:

git clone https://github.com/YOUR_GITHUB_USERNAME/dx-ball.git
cd dx-ball
scripts/bootstrap-python.sh
scripts/repo-python scripts/import-target.py /absolute/path/to/DX_Ball_Win_Preinstalled_EN.zip

Replace the archive path with your download. The importer verifies the ZIP and game files against the target configuration, then puts DXBALL.EXE and the assets in original/. It reports the number of verified and imported files. This directory is excluded from Git.

Install or update Codex and REA. The /goal workflow used below requires Codex 0.128.0 or newer:

npm install --global @openai/codex@latest rea-agents@latest
codex --version
rea --version

From the repository root, install the project's compiler and analysis tools:

scripts/repo-python scripts/bootstrap-tools.py
scripts/repo-python scripts/bootstrap-rea.py

The first command installs the JDK and Visual C++ 4.0 compiler. The second installs REA and Ghidra from the project's lock file, currently REA 6.4.0 and Ghidra 12.1.4. Both scripts verify their downloads and keep the tools in .tools/. The global REA CLI configures Codex; the project's scripts/rea command uses the locked tools for analysis.

Point REA at the installed Ghidra and JDK, then connect it to Codex:

export GHIDRA_INSTALL_DIR="$(pwd)/.tools/ghidra-rea"
export JAVA_HOME="$(pwd)/.tools/jdk"
rea setup --client codex
rea doctor --client codex --provider ghidra --json

Review and accept the changes shown by setup. It registers the REA MCP server, saves the Ghidra and JDK paths, and installs the REA skill that guides Codex's analysis. The doctor command checks the connection and provider; look for healthy: true. A failed check includes instructions for fixing it.

The REA setup guide also covers using an existing Ghidra installation. To update an existing integration, repeat the global installation and setup commands, then restart Codex. Project analysis follows the REA instructions.

From the same terminal, run:

codex

Sign in when prompted; the Codex CLI guide explains the authentication options. In Codex, enter /mcp to check that REA is connected. If Codex was open during REA setup, restart it to load the new registration.

Starting from the repository root gives Codex access to AGENTS.md, the original executable, recovered source, and research notes. The repository's instructions tell it which toolchain to use and where to resume recovery.

A Codex Goal lets Codex continue working toward an outcome across turns. Paste the following English prompt into Codex. It starts with function recovery, then moves to full game validation, and publishes verified checkpoints to your fork:

/goal Reconstruct English DX-Ball v1.07 from original/DXBALL.EXE as readable,
rebuildable C/C++. First recover every game-authored function as faithfully as
possible and maximize complete byte-exact matches with Visual C++ 4.0. Once
function recovery is complete, validate the rebuilt game's full behavior.

Read AGENTS.md, docs/agent/HANDOFF.md, and docs/agent/WORKFLOW.md. Continue from
the handoff, using REA to inspect unresolved functions and their callers,
callees, and data. Reuse saved evidence and recover related functions together.

Write typed source shared by the portable and legacy builds, preserving the
original calling conventions, integer widths, ownership, and state changes.
Recover the implementation from the evidence; avoid copied machine code,
assembly replacements, or padding added to force a match.
Compile each stable batch and compare whole functions with explicit mappings
for address references. Fix the differences and recheck affected exact matches.
Use focused checks to answer recovery questions along the way.

Record verified results in the match ledgers, progress, and handoff. Keep code
and documentation in English. Follow the project's resource limits and clean
disposable build products after preserving unique evidence. Commit verified
checkpoints with the prefix "gpt-6.1-sol: " and push to origin/main.

Report progress through recovered functions and exact matches. For remaining
mismatches, give the function addresses, comparison results, and next steps.

Use ordinary follow-up messages in the same thread to adjust priorities. Enter /goal to view the objective, /goal pause to pause work, and /goal resume to continue. Follow the results through the matching guide and source map.

If you also want to collect REA feedback, add this optional instruction. Keeping it in one file makes it easy to review without interrupting recovery:

Append useful REA feedback to /tmp/dxball-rea-feedback.md. Note slow calls,
oversized responses, token and context costs, and usability improvements,
with a concrete example when available. Keep this optional and brief;
function reconstruction remains the priority. Reuse the same document.

The diagram tracks recovered functions and exact compiler matches. See the progress records for current counts and the research notes for the recovered game flows.

• Build and play — supply the original files, compile, and launch.
• Source map — find the modules behind each part of the game.
• Architecture — follow startup, mode dispatch, and a frame.

DX-Ball was created by Michael P. Welch, with 3D graphics by Seumas McNally. Original game files are supplied separately. See LICENSE.