# Ace Combat 3: Electrosphere, recompiled

A native Windows port of the PlayStation game, made by translating its MIPS
code to C ahead of time and linking that against rewritten versions of the
Psy-Q libraries it used. There is no CPU emulator underneath.

Two programs come out of the build:

- `ac3.exe` draws the game the way the console did, in software, pixel for pixel.
- `ac3_enhanced.exe` adds a Vulkan renderer on top: higher resolution, 16:9,
  perspective-correct textures, and in flight a longer draw distance,
  atmosphere, clouds, ocean and forest.

**There is no game data in this repository.** No disc images, no executable,
and no translated game code either. The C version of the game's code is
generated on your machine, from your own disc, when you configure the build.
You need to own the game.

## What you need

The game: the Japanese release, both discs (SLPS-02020 and SLPS-02021), dumped
as `.bin` files with 2352-byte sectors. The build checks for the "Rev 1"
version, which is what Redump lists as

    Ace Combat 3 - Electrosphere (Japan, Asia) (Disc 1) (Rev 1).bin
    Ace Combat 3 - Electrosphere (Japan, Asia) (Disc 2) (Rev 1).bin

Keep those names. The launch scripts look for them.

Tools, all on your `PATH`:

| | Tested with | Notes |
|---|---|---|
| Visual Studio 2022 or its Build Tools | 17.x | "Desktop development with C++". clang uses its headers, libraries and the Windows SDK |
| LLVM (clang) | 22.1 | |
| CMake | 4.2 | 3.20 is the minimum |
| Ninja | 1.13 | |
| Python 3 | 3.12 | must run as `python` |
| Vulkan SDK | 1.4.350 | for `glslc`, the headers and the loader |
| SDL3, the VC development package | 3.4.8 | unpacked so that `C:\SDL3\include` and `C:\SDL3\lib\x64` exist |

Windows only, 64-bit, and a graphics card with a Vulkan driver.

## Building

1. Put the two disc images in `game\disc\`.

2. Copy the game's executable out of disc 1:

       python tools/ac3_disc.py extract "game/disc/Ace Combat 3 - Electrosphere (Japan, Asia) (Disc 1) (Rev 1).bin" ACE3.BIN game/ACE3.BIN

3. Configure and build:

       cmake -S . -B build -G Ninja -DCMAKE_C_COMPILER=clang
       cmake --build build

The configure step is where `game/ACE3.BIN` gets translated: it runs
`tools/recompile.py` and writes about 6 MB of C into `recomp/main/`. That
happens once. If the file is missing, or is not the Rev 1 executable, configure
stops and says so.

If SDL3 is somewhere else, add `-DSDL3_ROOT=D:/path/to/SDL3` to the first
command. If `ACE3.BIN` is somewhere else, `-DAC3_GAME_EXE=...`.

A full build takes well under a minute on a recent machine. You end up with
`build\ac3.exe`, `build\ac3_enhanced.exe` and a copy of `SDL3.dll` beside them.

To translate the game again (after changing the recompiler, say), delete
`recomp\main` and run the configure command once more.

## Running

    play.bat                    the original look
    play_enhanced.bat           the enhanced renderer
    play_enhanced.bat 2         boot from disc 2 instead

Both discs are mounted together, so the game never asks you to change disc.
Saves go to `saves\card1.mcd` and `saves\card2.mcd`, which are ordinary memory
card images.

A controller works if SDL recognises it. On the keyboard:

| Key | Button |
|---|---|
| Arrows | D-pad |
| W A S D | Left stick |
| X, C, Z, V | Cross, Circle, Square, Triangle |
| Q, E | L1, R1 |
| 1, 3 | L2, R2 |
| Enter | Start |
| Right Shift or Backspace | Select |
| Esc | Quit |

In the enhanced build, F1 opens a settings menu (resolution, widescreen, the
individual effects, language, volume), F7 switches the world effects on and
off, and F11 toggles fullscreen. Settings are kept in `ac3_settings.ini`.

Anything after the disc number is passed to the game, for example
`play_enhanced.bat 1 --scale 6 --no-clouds`. The options: `--scale N` (1 to 8),
`--no-widescreen`, `--no-perspective`, `--no-pgxp`, `--no-fx`, `--no-far`,
`--no-atmosphere`, `--no-gi`, `--no-ocean`, `--no-forest`, `--no-clouds`,
`--no-sun`, `--one-disc`, `--disc2 <image>`.

## English

The game is Japanese. Team NEMO's fan translation (v0.9b3) is supported and included

to pick English press F1 > Game in the enhanced build, or pass `--english`
(`play.bat 1 --english`). `--japanese` goes back.

Your disc images are not modified. The patch is applied in memory when the
game starts, and the result is cached in a `.en.cache` file next to each image
so the next start is quick.

## Checking a build

    build\ac3.exe --selftest-gpu
    build\ac3.exe --selftest-raster
    build\ac3.exe --selftest-libgpu
    build\ac3.exe --selftest-gte
    build\ac3.exe --selftest-libc
    build\ac3.exe --selftest-card
    build\ac3.exe --selftest-spu <disc 1 image>
    build\ac3.exe --japanese --selftest-cd <disc 1 image>
    build\ac3.exe --selftest-english <disc 1 image>
    build\ac3_enhanced.exe --selftest-hw

Each prints `SELFTEST PASSED` or says what failed. `--selftest-english` needs
the translation patch in place. Run them from the project folder.

## What is in here

    CMakeLists.txt          the build
    play.bat, play_enhanced.bat
    host/                   program entry, boot, self-tests
    runtime/                CPU context, memory, GTE, interpreter for overlays
      hle/                  the rewritten Psy-Q libraries, software GPU, SPU, CD
    renderer/               Vulkan output, SDL input and audio
      hw/                   the enhanced renderer and its menu
      shaders/              GLSL, compiled and embedded by the build
    recomp/
      analysis.json         where the game's functions and jump tables are
      psyq_symbols.json     which of them are Psy-Q library functions
      main/                 generated: the game's code as C (not in git)
    tools/
      recompile.py          MIPS to C
      ac3_analyze.py, mips.py   what recompile.py is built on
      ac3_disc.py           reads files out of a disc image
      embed_spv.py          turns compiled shaders into a header
    third_party/imgui/      Dear ImGui 1.92.9b (MIT), used by the settings menu
    game/                   yours: disc images, ACE3.BIN, translation (not in git)

`recomp/analysis.json` and `recomp/psyq_symbols.json` are lists of addresses
and names. They describe the executable; they do not contain any of it.

## If it does not build

- `game/ACE3.BIN not found`: do step 2.
- `is not the executable this project was written against`: your dump is a
  different revision. Only Rev 1 works.
- `Could NOT find Vulkan (missing: glslc)`: install the Vulkan SDK and open a
  new terminal so its environment variables are picked up.
- `SDL3/SDL.h file not found` or a missing `SDL3.lib`: SDL3 is not at
  `C:\SDL3`. Pass `-DSDL3_ROOT=...`.
- `'python' is not recognized`: Python is installed as `py` or `python3` only.
  Add a `python` to your `PATH`.
- Missing `stdio.h`, `windows.h` or `kernel32.lib`: clang cannot find Visual
  Studio. Install the C++ workload, or build from a "x64 Native Tools Command
  Prompt".