# Space Invaders 8080 Static Recompiler

A static binary recompiler that translates the original 1978 Space Invaders arcade ROM into native C++ code, producing a playable emulator.

Unlike traditional interpreters that decode each instruction at runtime, this project performs ahead-of-time translation: a lifter tool reads the ROM, performs control flow analysis, and generates a C++ switch/case with one entry per instruction address. The result runs at native speed with cycle-accurate timing and interrupt delivery.

## Architecture

The project consists of several components:

| File | Purpose |
|------|---------|
| `lifter.cpp` | Translates individual 8080 instructions into C++ code strings |
| `lifter_tool.cpp` | ROM control flow analysis (linear sweep + branch target discovery), generates `invaders_recompiled.cpp` |
| `cpu_8080.h` | CPU state struct, flag helpers, parity lookup table |
| `cpu_8080.cpp` | I/O port emulation (input ports, hardware shift register, sound ports) |
| `interpreter_8080.h` | Runtime interpreter fallback for computed jumps (PCHL) |
| `emulator_runner.cpp` | SDL3 frontend: rendering, input, frame timing |
| `rom_loader.h` | ROM file loading |
| `test_lifter.cpp` | 130+ regression tests covering all 8080 opcodes |

### How It Works

1. **Lifter tool** reads the four ROM files and performs two-pass analysis:
   - **Pass 1 (linear sweep):** Walks ROM sequentially, recording instruction boundaries
   - **Pass 2 (branch targets):** Collects all JMP/CALL/Jcc/Ccc/RST targets and discovers mid-instruction entry points

2. **Code generation** produces `invaders_recompiled.cpp` containing:
   - A `run_cpu()` function with a giant switch/case (one case per instruction address)
   - Cycle-based interrupt delivery (RST 1 at mid-frame, RST 2 at vblank)
   - EI instruction timing (delays interrupt enable by one instruction, matching real 8080 behavior)

3. **Emulator runner** ties it together with SDL3:
   - Runs ~33,332 cycles per frame at 2 MHz
   - Rotates the column-major VRAM into a landscape display
   - Polls keyboard state for arcade controls
   - Throttles to 60 Hz with sub-millisecond precision

## Prerequisites

- A C++ compiler with C++11 support (g++, clang++, or MSVC)
- [SDL3](https://github.com/libsdl-org/SDL) development libraries
- Space Invaders ROM files (not included -- see below)

## ROM Files

You must supply your own Space Invaders ROM files. These are copyrighted by Taito and cannot be distributed with this project.

Place the following files in a `Data/` subdirectory:

```
Data/invaders.h    (2048 bytes, mapped to 0x0000-0x07FF)
Data/invaders.g    (2048 bytes, mapped to 0x0800-0x0FFF)
Data/invaders.f    (2048 bytes, mapped to 0x1000-0x17FF)
Data/invaders.e    (2048 bytes, mapped to 0x1800-0x1FFF)
```

## Building

### Step 1: Run the test suite (no ROM or SDL required)

```bash
g++ test_lifter.cpp cpu_8080.cpp -o test_lifter
./test_lifter
```

### Step 2: Generate recompiled code from ROM

```bash
g++ lifter_tool.cpp lifter.cpp cpu_8080.cpp -o lifter_tool
./lifter_tool
```

This reads the ROM files and produces `invaders_recompiled.cpp`.

### Step 3: Build the emulator

```bash
g++ emulator_runner.cpp invaders_recompiled.cpp cpu_8080.cpp -o invaders -lSDL3
./invaders
```

On Windows with SDL3.dll in the current directory, you may need to adjust the include/library paths to point to your SDL3 installation.

## Controls

| Key | Action |
|-----|--------|
| C | Insert coin |
| Enter | P1 Start |
| Space | P1 Fire |
| Left Arrow | P1 Move left |
| Right Arrow | P1 Move right |

## Technical Details

- **CPU:** Intel 8080 running at 2 MHz (2,000,000 cycles/sec)
- **Display:** 256x224 monochrome, rotated 90 degrees from column-major VRAM
- **Interrupts:** Two per frame -- RST 1 (0x0008) at mid-screen, RST 2 (0x0010) at vblank
- **Shift register:** External 16-bit hardware shift register for sprite positioning (the 8080 has no barrel shift instruction)
- **Memory map:** 0x0000-0x1FFF ROM, 0x2000-0x23FF RAM, 0x2400-0x3FFF Video RAM

## License

This project is licensed under the MIT License -- see [LICENSE.txt](LICENSE.txt) for details.

SDL3 is used under the [zlib license](https://github.com/libsdl-org/SDL/blob/main/LICENSE.txt).

Space Invaders is a trademark of Taito Corporation. ROM files are not included.