# AeroGauge: Recompiled

![AeroGauge: Recompiled fan art by Gary (POOTERMAN)](docs/aerogauge-fan-art.png)

AeroGauge: Recompiled is a PC version of the Nintendo 64 racing game AeroGauge.
It runs your own copy of the game in a native window.

This version includes an in-game settings screen. Some visual enhancements and
less common hardware paths still need more testing; see Known limitations.
The details below describe this checkout. A release archive can predate it, so
check the release notes before expecting newly merged features.

## Supported computers

Release targets are:

- Windows 10 or later, 64-bit, with Direct3D 12 support.
- Linux, 64-bit, with Vulkan support.
- Android 9 or later, ARM64, with a compatible Vulkan driver. See
  [Android setup](docs/android.md) for touch controls, ROM import, and GPU drivers.

macOS is not a supported target in this branch. A build that compiles on
another system is not proof that the game runs there.

## Run a release

On Android, install the APK and use **Import ROM** in the app, then **Play
AeroGauge**. See [Android setup](docs/android.md). Desktop instructions:

1. Download the archive for your system from
   [GitHub Releases](https://github.com/alondero/aerogauge-recomp/releases).
2. Extract it to a folder.
3. Put your legally dumped USA or Japanese Rev A game in that folder. Use
   `AeroGauge (USA).z64` or `AeroGauge (Japan) (Rev A).z64` (Japanese `.n64`
   and `.v64` dumps are also detected).
4. On Windows, start `aerogauge_modern.exe`. On Linux, start
   `./aerogauge_modern`. To add AeroGauge to the Linux applications menu with
   its icon (including native Wayland taskbars), run
   `./install_linux_launcher.sh` once and start it from the menu. If you move
   the extracted folder, run the installer again to refresh the launcher.

The archive contains the program and its support files. It does not contain the
game ROM. If both ROMs are present, USA is the default; pass a ROM path as the
program's first argument to select either version. Japanese Rev A retains its
original title, vehicle/course/difficulty names, announcer, and game behavior.
Each region has separate game saves. Other revisions, including the original
Japanese release, are not supported.

## Build from source

Building from source is a developer task and requires a matching ROM. See
[BUILDING.md](BUILDING.md) for the tools and complete commands.

## Controls

These are the default port bindings:

| Action | Keyboard | Gamepad |
| --- | --- | --- |
| Confirm / accelerate | X | A |
| Cancel / brake | C | B |
| Steer | Arrow keys or W/A/S/D | Left stick |
| Drift | Z | Left trigger |
| Pause / advance | Enter | Start |
| L button | Q | Left shoulder |
| R button | E or R | Right shoulder or right trigger |
| C buttons | I/J/K/L | X/Y/right stick |

The port exposes one physical controller as Controller 1.

## Settings

The desktop app starts AeroGauge directly. Set `AERO_LAUNCHER=1` to open the
launcher first and choose **Start Game**, **Settings**, or **Mods**. During play,
open Settings with **Escape**, **F10**, or controller **Back**. This also works
in fullscreen. Use the mouse, keyboard, or controller D-pad; the screen shows
the active button prompts. See [Configuration](docs/configuration.md) for what
`AERO_LAUNCHER` reaches.

The **Graphics** page controls resolution, widescreen display, HUD placement,
presentation rate, anti-aliasing, window mode and size, and texture paths.
**Force Full LOD** keeps cars at maximum model detail and removes their distance
cutoff; the Draw distance setting still controls far clipping. It is off by default.
Press **Apply** to keep graphics changes. Press **Discard** to cancel them.

For weaker hardware, choose **Rendering preset > Low power** on Graphics and
press **Apply**. It uses native resolution, no anti-aliasing, the original
presentation rate, and standard colour precision. For a further reduction in
geometry work, turn off **Full course geometry** in Enhancements and set the
draw distance multiplier to 1.

The **Enhancements** page controls draw distance, full-course geometry, and
separate Player 1 and Player 2 Easy Turbo + Boost Start options. These changes are saved as soon as they are made.
Full-course geometry is experimental and can cost performance or show visual
errors. Easy Turbo changes the driving controls; it is off by default.
With Easy Turbo on, press the R button during a race to start Turbo and use the
assisted Boost Start.

For two players, open **Controls > Assign players**. Press a button on each
gamepad in player order, or assign the keyboard to one player, then confirm.
Use each player's **Edit Profile** to configure driving and menu bindings.
Choose the game's **2 Players** mode to race in split screen. Assign devices
again after restarting or reconnecting a controller; saved bindings and profile
choices are retained. Before assignment, keyboard and gamepads share Player 1.
See [Controllers](docs/controllers.md) for device and assist behavior.
F11 and Alt+Enter switch fullscreen. Graphics API and texture-path changes take
effect after a restart.

The **Mods** page installs and manages AeroGauge packages. Install packages
before starting the game; scanning and installation are disabled while it is
running. Code mods load at game start and require a restart after changing
them. RT64 texture packs can be enabled, disabled, and reordered while playing.
Mod support is experimental; see [Modding](docs/modding.md) for package
requirements and limits.

## Saves and files

The program stores its files in these locations:

- Windows: `%LOCALAPPDATA%\AeroGaugeRecomp\`
- Linux: `$XDG_CONFIG_HOME/AeroGaugeRecomp`, or
  `~/.config/AeroGaugeRecomp`
- Portable mode: the folder from which you run the program, when that folder
  contains a file named `portable.txt`

The contents of `portable.txt` do not matter. Its presence selects portable
mode.

`graphics.json` stores display settings, including draw distance and
full-course geometry. `enhancements.json` stores the Easy Turbo + Boost
Start assist setting. Game saves are in the `saves` subfolder. Back up
that folder before testing a new build.

## Known limitations

- Supported ROMs are USA and Japan Rev A. Local USA-only builds remain possible.
- Full-course geometry is experimental.
- Texture dumping remains a developer feature.
- Mod support is experimental, and packages must target AeroGauge Recompiled.
- Platform, graphics-driver, and physical-controller coverage is incomplete.
- The settings screen is not shown by headless test runs.

See the [documentation map](docs/README.md) for developer documentation, test
commands, and configuration details.

## Special thanks

Thanks to [Gary (POOTERMAN)](https://www.deviantart.com/pooterman) for creating
and sharing the fan art featured at the top of this README and used for the
Windows, Linux, and Android application icons.

## License

Project code is licensed under [LICENSE](LICENSE). The game and dependency
submodules have their own licenses. You must provide your own ROM.