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.skirmish    ra3.client        ra3.game         ra3.map
   match rules     display/loop      RA3 sides        map catalog
        │               │                 │               │
        └───────┬───────┴────────┬────────┘               │
                ▼                ▼                        ▼
           ra3.logic         ra3.core                  ra3.fs
           simulation        types/math/random         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.

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.