136 lines
5.3 KiB
Markdown
136 lines
5.3 KiB
Markdown
# Reverse engineering workflow
|
|
|
|
OpenRA3 is reconstructed from two sources:
|
|
|
|
1. **Architecture** — the GPLv3 SAGE 1.0 tree,
|
|
[`electronicarts/CnC_Generals_Zero_Hour`](https://github.com/electronicarts/CnC_Generals_Zero_Hour).
|
|
RA3 runs SAGE 2.0, so class names, message flow and subsystem boundaries
|
|
carry over even though the code does not.
|
|
2. **Facts** — the retail `ra3_1.12.game` binary (image base `0x400000`),
|
|
analysed in Ghidra and, when needed, observed live.
|
|
|
|
Nothing in OpenRA3 should assert a structure or constant that is not either
|
|
copied from the reference or cited to a retail address.
|
|
|
|
## Fetching the reference
|
|
|
|
```bash
|
|
tools/fetch_reference.sh # sparse-clone Code/GameEngine into reference/
|
|
```
|
|
|
|
The checkout is git-ignored (large, and GPLv3 terms differ from this repo's).
|
|
|
|
## Ghidra
|
|
|
|
The retail module is loaded into Ghidra as `ra3_1.12.game`
|
|
(`x86:LE:32:default`, 34k+ functions). The analysis is driven through the
|
|
Ghidra MCP bridge, so every recovered fact can be re-derived:
|
|
|
|
| Question | Tool call |
|
|
| --- | --- |
|
|
| What does an address do? | `decompile_function(address=0x…)` |
|
|
| What is this function? | `get_function_by_address(address=0x…)` |
|
|
| Who touches a global? | `get_xrefs_to(address=0x…)` |
|
|
| What are the vtable slots? | `list_class_members` / `analyze_data_region` |
|
|
| Where is a string referenced? | `search_strings` + `get_xrefs_to` |
|
|
|
|
### Recovery loop
|
|
|
|
1. Pick a subsystem from the reference tree (e.g. `MessageStream`).
|
|
2. Find its RTTI/vtable in the binary via `search_strings` and xrefs.
|
|
3. Decompile the constructor to recover object size and field init order.
|
|
4. Decompile the hot methods to recover field meaning.
|
|
5. Write the OpenRA3 module with a comment citing the address.
|
|
6. Add a smoke test that pins the behaviour.
|
|
|
|
## Recovered symbol map (retail `ra3_1.12.game`)
|
|
|
|
### Engine singletons
|
|
|
|
Each holds an object pointer (0 when the subsystem is down).
|
|
|
|
| Global | Address | Object vtable |
|
|
| --- | --- | --- |
|
|
| `TheGameLogic` | `0x00cd8ce4` | `0x00beb630` |
|
|
| `ThePlayerList` | `0x00ce8c9c` | `0x00c5b9e0` |
|
|
| `ThePartitionManager` | `0x00ce2f9c` | `0x00c6af98` |
|
|
| `TheShroudManager` | `0x00ce2fa0` | `0x00c6aefc` |
|
|
| `ThePlacementGrid` | `0x00cd8d0c` | `0x00bea560` |
|
|
| `TheRecorder` | `0x00ce2fd0` | `0x00c10544` |
|
|
| `TheGlobalObjectRegistry` | `0x00cd8d08` | `0x00bea644` |
|
|
| `ThePlayerTemplateStore` | `0x00ce8ca0` | `0x00c5bc70` |
|
|
| `TheGameState` | `0x00cdbbc4` | `0x00bef0c0` |
|
|
| `GlobalData` | `0x00ce2fa8` | `0x00c0d8e4` |
|
|
| `TheMessageStream` | `0x00ce2fb8` | `0x00c0ecd4` |
|
|
|
|
### Reconstructed layouts
|
|
|
|
- **`GameLogic`** — tick counter at `+0x50` (incremented once per 30 Hz
|
|
simulation step); `starting` guard flag at `+0xa7`, raised while a new match
|
|
initialises.
|
|
- **`MessageStream`** — intrusive doubly linked list; head at `+0x24`, tail at
|
|
`+0x28`. `appendMessage` (`0x0060c4a0`) allocates a `0x74`-byte node:
|
|
`+0x00` next, `+0x04` prev, `+0x08` owner stream, `+0x0c` message type,
|
|
`+0x10` player index, `+0x18` capacity, `+0x1c` data pointer (`node + 0x20`).
|
|
- **`Player`** — money via `std::vector<Money*>` at `+0xe4`; power at `+0x74`;
|
|
team at `+0xac`; relation maps at `+0xfc` / `+0x100`.
|
|
- **Skirmish setup** (`SkirmishGameInfo`, pointer at `[0x00ce3a78]`) — starting
|
|
cash `+0x64`, player slots `+0xfc` (stride `0x5c`, 6 slots), faction at
|
|
`slot + 0x18` (`Empire=2`, `Allied=4`, `Soviet=8`, `Random=7`).
|
|
|
|
### Match start
|
|
|
|
The BEGIN button calls `SkirmishGameOptionsMenu::start` (`0x00b28d60`), which
|
|
copies the map, calls `GameInfo::startGame(0)`, seeds the logic random and
|
|
appends `MSG_NEW_GAME` (`0x2`). `startNewGame` itself is `0x00623e40`. OpenRA3
|
|
mirrors this two-phase `prepare_new_game` / `start_new_game` split.
|
|
|
|
## Container and map formats
|
|
|
|
Recovered by inspection of `Data\*.big` (see `ra3.fs` / `ra3.map`).
|
|
|
|
### `BIG4` archive
|
|
|
|
All integers little-endian except where noted:
|
|
|
|
```
|
|
offset 0 magic "BIG4"
|
|
offset 4 fileSize u32 LE total archive size
|
|
offset 8 fileCount u32 BE number of entries
|
|
offset 12 indexSize u32
|
|
offset 16 entries fileCount * { offset u32 BE, size u32 BE, name cstring }
|
|
```
|
|
|
|
Entry offsets are absolute; payloads are RefPack-compressed.
|
|
|
|
### RefPack
|
|
|
|
EA's `10 FB` stream. `ra3.fs::refpack_decompress` implements the 2/3/4-byte
|
|
commands and the long-literal/stop opcodes; `refpack_output_size` reads the
|
|
declared output length without decompressing.
|
|
|
|
### Map file (`.map`)
|
|
|
|
Two layers of compression:
|
|
|
|
```
|
|
BIG4 payload = RefPack -> "EAR\0" + u32 unpacked_size + RefPack -> "CkMp" ...
|
|
```
|
|
|
|
The `CkMp` payload is the compiled SAGE map: a type/field name table followed by
|
|
chunk data. Player start positions appear as waypoints named
|
|
`Player_1_Start`, `Player_2_Start`, ... Each waypoint record carries a `Coord3D`
|
|
(three little-endian `float`s) shortly after the name; `ra3.map` scans forward
|
|
from the name for the first plausible `(x, y, 0)` triple. Maps that store starts
|
|
in `MPPositionList` instead yield no waypoints and fall back.
|
|
|
|
Verified example (`map_mp_2_feasel4`): `Player_1_Start` = `(1338.9, 1940.5, 0)`,
|
|
`Player_2_Start` = `(1290.8, 1404.9, 0)`.
|
|
|
|
### Still to recover
|
|
|
|
- `MPPositionList` layout (per-player starts for maps without waypoints).
|
|
- Map dimensions / `HeightMapData` / `BlendTileData`.
|
|
- Compiled asset blobs (`map.bin`, `global.bin`, `static.*.bin`) and the
|
|
`.manifest` schema used to deserialise them.
|