OpenRA3 v0.0.1: C++26 modules, BIG4/RefPack reader, minimal skirmish

2026-09-12 00:26:45 +08:00
commit 3ad380c81e
24 changed files with 2630 additions and 0 deletions
@@ -0,0 +1,78 @@
+# 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_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.
+
+## 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.