# Architecture

OpenRA3 is organised as a stack of C++26 modules. Each layer may import the ones
below it, never the ones above. Every module uses `import std;` for the standard
library; the engine is built with Clang + libc++ on Linux and cross-compiled
with llvm-mingw for Windows.

```
                 ┌───────────────────────────────────────┐
   applications  │  openra3 (apps/openra3)               │
                 └───────────────────┬───────────────────┘
                                     │ import ra3
                 ┌───────────────────▼───────────────────┐
   umbrella      │  ra3  (re-exports everything)         │
                 └───────────────────┬───────────────────┘
      ┌──────────────┬───────────────┼───────────────┬──────────────┐
      ▼              ▼               ▼               ▼              ▼
  ra3.ui        ra3.render      ra3.skirmish    ra3.client      ra3.game
  SDL3 window   framebuffer     match rules     display/loop    RA3 sides
      │              │               │               │              │
      └──────┬───────┘               └───────┬───────┘              │
             ▼                               ▼                      │
          ra3.core                       ra3.logic                  │
                                         simulation                 │
      ┌───────────────────────────────────────┬──────────────────────┘
      ▼                                       ▼
  ra3.map                                 ra3.fs
  map catalog                             BIG4 + RefPack
```

## Module responsibilities

### `ra3.core`
The vocabulary every other module shares, mirroring SAGE's `GameEngine/Common`:
`real`/`int32`/`uint32`, `coord3d`/`coord2d`/`rgb_color`, `ascii_string` +
`make_name_key`, the deterministic `random` stream, and the `message_stream`
command bus (node layout derived from retail `MessageStream::appendMessage`,
`0x0060c4a0`).

### `ra3.logic`
The deterministic simulation, mirroring SAGE's `GameLogic`: `thing` → `object`
with pluggable `update_module`s, `player`/`player_list`, the `partition_manager`
spatial grid, and the 30 Hz `game_logic` driver (`prepare_new_game` /
`start_new_game` / `update`).

### `ra3.client`
The presentation boundary: an abstract `display` with a `headless_display`
implementation, and `game_client`, the seam a future W3D/D3D9 renderer plugs
into.

### `ra3.game`
Red Alert 3 data that SAGE keeps in `PlayerTemplate`: the three sides
(`faction` flags `Empire=2`, `Allied=4`, `Soviet=8`, `Random=7`, recovered from
the retail skirmish setup) and skirmish defaults.

### `ra3.fs`
Reading the user's installation. Implements the `BIG4` archive container and
EA's RefPack codec, plus `find_game_dir` (`--game-dir` / `$RA3_GAME_DIR` /
`C:\Red Alert 3`). Only the archive index is held in memory; payloads are read
on demand.

### `ra3.map`
Map discovery and loading: scans `MapsMultiplayer.big` for main map entries,
unwraps the two compression layers (`BIG4` RefPack → `EAR\0` wrapper → RefPack →
`CkMp`), and recovers `Player_N_Start` waypoint coordinates. Degenerate
extractions are rejected so the caller can fall back.

### `ra3.skirmish`
The minimal match: two players, unit classes (harvester/infantry/tank/base),
passive + harvester income, a simple build AI, movement and combat on a fixed
30 Hz step, and a base-destruction win condition. Fully deterministic.

### `ra3.render`
A dependency-free software renderer: an ARGB8888 `image` framebuffer with
blit/line/circle primitives, a TGA decoder for the game's map art, a 24-bit BMP
encoder for headless output, and `compose` which overlays a world grid and
markers (start positions, live units) onto the map art.

### `ra3.ui`
The windowed viewer. The SDL3 backend streams the rendered image to a texture
with pan/zoom and Esc-to-quit; when the build has no SDL3, a null backend
returns `false` so the caller writes an offscreen image instead.

## Design rules

1. **No raw owning pointers.** Ownership is `std::unique_ptr`; the partition
   manager holds non-owning `thing *` views only.
2. **Portable simulation.** No platform APIs in `ra3.core` / `ra3.logic`. All
   platform concerns live behind `display`.
3. **Determinism.** Anything that can diverge between runs (random, iteration
   order) is explicit and seedable.
4. **RE-traceable.** Where a structure or constant comes from the retail
   binary, the address is cited in the comment.
5. **No bundled assets, no online.** Game data is read from the user's install
   and never committed; there is no networking or online service.