OpenRA3/docs/REVERSE_ENGINEERING.md

Reverse engineering workflow

OpenRA3 is reconstructed from two sources:

1. Architecture — the GPLv3 SAGE 1.0 tree, 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

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 floats) 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.