OpenRA3/docs/ARCHITECTURE.md

Architecture

OpenRA3 is organised as a stack of C++ modules. Each layer may import the ones below it, never the ones above.

                 ┌───────────────────────────────────────┐
   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_modules, 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.