# 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.display ra3.render ra3.skirmish ra3.client ra3.game backend pick framebuffer match rules display+loops RA3 sides │ │ │ │ │ ┌──┴───┐ │ └───────┬───────┘ │ ▼ ▼ ▼ ▼ │ ra3.ui ra3.vulkan ra3.terrain ra3.logic │ SDL Vulkan heightmap/blends simulation │ ┌──────────────────────┘ ▼ ra3.map / ra3.fs catalog / BIG4 + RefPack ``` ## Presentation layer `ra3.client::display` is the single seam between the engine and the windowing stack. A backend implements only the low-level primitives (`init`, `present`, `poll_event`, `window_size`, `key_down`, `shutdown`) and, optionally, `present_terrain`; the interactive loops (menu, image viewer, camera viewer, GPU terrain) and the native-to-`ui_event` mapping live once in the base class, so the SDL and Vulkan paths cannot drift. SDL3 remains the platform layer (it owns the window, input and the low-cost blit backend); Vulkan is the accelerated backend. `ra3.display` selects the first backend that starts, and the app never references a backend by name. The Vulkan backend currently hand-rolls its pipelines. As materials, skybox and HUD arrive, a thin RHI + render-graph belongs between `ra3.client` and the Vulkan/SDL backends; `present_terrain` is the placeholder for that step. ## 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: the abstract `display` (low-level primitives plus the shared interactive loops and `ui_event` mapping), a `headless_display` for CPU-only runs, and `game_client`, the facade that owns the simulation and drives the frame loop. ### `ra3.display` Backend selection: tries Vulkan, then SDL, then reports failure so the caller can fall back to an offscreen image. The only module that names a concrete backend. ### `ra3.terrain` The real map terrain: parses `CkMp`'s `HeightMapData` and `BlendTileData` (tiles, `Blends`/`ThreeWayBlends` and their `BlendDescription`s), loads the `Terrain.big` tile textures, and rasterises the map (software `render`/`render3d` and the GPU `gpu_terrain` for `present_terrain`). ### `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`), recovers `Player_N_Start` waypoint coordinates, and decodes the localized display names from the install's `gamestrings.csf`. 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/text primitives (an embedded 8x8 bitmap font), 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 SDL3 backend: `sdl_display` implements the `ra3.client::display` primitives using an `SDL_Renderer` streaming texture. Cheap and dependency-light, it is the fallback when Vulkan is unavailable. A null backend returns `false` so the build still runs without SDL3. ### `ra3.vulkan` The accelerated backend: `vulkan_display` implements the same primitives and adds `present_terrain`, a GPU heightfield raymarcher (mipmapped tile atlas with a replicated gutter and the retail SAGE blend ramp). A null backend reports failure when no Vulkan loader is present. ## 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.