Merge remote-tracking branch 'origin/master' into HEAD

Author: madebr

CLAUDE.md

@@ -29,6 +29,10 @@ pip install -r tools/requirements.txt
 reccmp-reccmp --target LEGORACERS --print-rec-addr
 reccmp-reccmp --target GOLDP --verbose 0x100070b0 --print-rec-addr
 
+# Compare global variable data values
+reccmp-datacmp --target LEGORACERS --verbose --print-rec-addr
+reccmp-datacmp --target GOLDP --verbose --print-rec-addr
+
 # Progress SVGs
 reccmp-reccmp --target LEGORACERS --total 3986 --nolib -S LEGORACERSPROGRESS.SVG --svg-icon assets/legoracers.png
 reccmp-reccmp --target GOLDP --total 1071 --nolib -S GOLDPPROGRESS.SVG --svg-icon assets/goldp.png
@@ -55,6 +59,15 @@ Functions in a compilation unit must be ordered by address (ascending).
 // SIZE 0xc8ac8                      — struct/class size assertion
 ```
 
+**GLOBAL variables** have a pointer address and may point to initialized data. A `// GLOBAL:` annotation marks the address of the pointer variable itself. If the variable is a `char*` pointing to a string literal, the address of where the string data lives should be in `reccmp/lego-racers-ascii.csv`
+
+```cpp
+// GLOBAL: LEGORACERS 0x4be8d8      — address of the pointer variable
+LegoChar* g_jamFile = "lego.jam";
+```
+
+When adding or modifying globals, always run `reccmp-datacmp` to verify the initial values match the original binary. Global variables with non-zero initial values (strings, pointers, constants) must be initialized to match.
+
 **FOLDED functions:** MSVC 6.0's linker merges functions with identical compiled code (Identical COMDAT Folding). Multiple distinct functions end up sharing one address in the original binary. Annotate each with `// FUNCTION: MODULE 0xADDRESS FOLDED` where the address is the single copy the linker kept. All folded functions share the same address. Functions that fold together have the same signature and body (e.g. all empty `void` methods fold to one address, all empty `void(undefined4)` methods fold to a different address). FOLDED functions are exempt from the address-ascending ordering rule and do not need the `STUB()` anti-folding macro.
 
 ## Class Pattern
@@ -83,6 +96,13 @@ DECOMP_SIZE_ASSERT(VelvetThunder0xc8ac8, 0xc8ac8)
 
 Member offset comments (`// 0xNN`) and vtable offset comments (`// vtable+0xNN`) are required.
 
+**Gap members:** When declaring `undefined` arrays to fill gaps between typed members, use a subtraction expression rather than a hardcoded size. This makes the size self-documenting and avoids manual recalculation when members are added:
+
+```cpp
+undefined m_unk0x05[0x7dc - 0x05];   // 0x05  (gap until next member at 0x7dc)
+undefined m_unk0x92c[0x944 - 0x92c]; // 0x92c (gap until end of class at 0x944)
+```
+
 **Overrides:** When a derived class overrides a virtual method from a base class, use `override` instead of `virtual` (e.g. `void VTable0x04() override;`). Include `compat.h` which defines `override` as empty for MSVC 6.0 compatibility.
 
 ## Naming Conventions
@@ -129,6 +149,8 @@ When a variable's type is dictated by an external interface (Windows API return
 
 7. **Build with double `cmake --build`**, then compare: `reccmp-reccmp --target LEGORACERS --verbose 0xADDRESS --print-rec-addr`. Iterate until 100%.
 
+7b. **Verify global data** with `reccmp-datacmp --target LEGORACERS --verbose --print-rec-addr`. Any `// GLOBAL:` variable with non-zero initial data must match the original binary. This catches uninitialized globals that should have string pointers, default values, etc.
+
 8. **Validate vtables.** After adding or modifying virtual methods, always verify the vtable matches: `reccmp-reccmp --target LEGORACERS --verbose 0xVTABLE_ADDR --print-rec-addr`. Every virtual method declared in a class header must have a corresponding `// STUB:` annotation with its real address from the original binary. Read the vtable data from the original binary to find the function address at each vtable slot.
 
 9. **Check for regressions.** After any change, re-verify all previously matched `// FUNCTION:` implementations that touch the same classes, especially functions that make virtual calls on modified classes.
@@ -160,6 +182,7 @@ Matching these three functions provides high confidence that the class header (s
 
 - **Return types affect register allocation.** Changing a function from `void` to returning a pointer/int can significantly change which registers the compiler assigns to local variables and parameters. If register allocation doesn't match, check whether the original function returns a value (IDA's guessed return type is a hint).
 - **Float literal assignments may compile to integer `mov`.** MSVC 6.0 with `/O2` optimizes `float_member = 1.0f` to `mov dword ptr [offset], 0x3F800000` (an integer immediate store) rather than `fld`/`fstp`. Using `LegoFloat` members with float literals still produces the correct integer stores.
+- **Inline getters/setters produce matching code for cross-object member access.** When a function accesses internal members of a composed sub-object (e.g. `NeonCactus` accessing `IronFlame`'s private members), use public inline getters/setters on the sub-object class. MSVC 6.0 with `/O2` inlines these, producing identical code to direct member access — and can even improve register scheduling to match the original binary more closely than making members public.
 - **Write human-readable code, not IDA pseudocode.** The decompiled code should look like it was written by a human programmer. Avoid `goto` patterns, raw integer bit patterns for floats, and other artifacts of decompilation. Use proper types, named variables, and clean control flow. Iterate with reccmp to ensure the clean version still matches.
 
 ## Project Structure

CMakeLists.txt

@@ -101,6 +101,9 @@ add_executable(legoracers WIN32
   LEGORacers/src/frostpetal0x34.cpp
   LEGORacers/src/emberdust0x28.cpp
   LEGORacers/src/cobaltmist0x30.cpp
+  LEGORacers/src/tealpulse0x24.cpp
+  LEGORacers/src/crimsonforge0x800.cpp
+  LEGORacers/src/opalvault0xf0.cpp
   LEGORacers/src/silvernode0x50.cpp
   LEGORacers/racers.rc
 )

LEGORacers/include/amberwolf0x98.h

@@ -13,6 +13,7 @@
 // SIZE 0x98
 class AmberWolf0x98 : public IndigoStar0x18 {
 public:
+	AmberWolf0x98();
 	~AmberWolf0x98() override;                  // vtable+0x00
 	undefined4 VTable0x04(undefined4) override; // vtable+0x04
 	void VTable0x08() override;                 // vtable+0x08
@@ -30,17 +31,26 @@ class AmberWolf0x98 : public IndigoStar0x18 {
 	// AmberWolf0x98::`scalar deleting destructor'
 
 private:
-	undefined4 m_unk0x18;      // 0x18
-	undefined m_unk0x1c[0x08]; // 0x1c
-	IUnknown* m_unk0x24;       // 0x24
-	undefined m_unk0x28[0x08]; // 0x28
-	IUnknown* m_unk0x30;       // 0x30
-	undefined m_unk0x34[0x08]; // 0x34
-	ListHead m_unk0x3c;        // 0x3c
-	ListHead m_unk0x48;        // 0x48
-	undefined4 m_unk0x54;      // 0x54
-	undefined4 m_unk0x58;      // 0x58
-	undefined m_unk0x5c[0x3c]; // 0x5c
+	undefined4 m_unk0x18;             // 0x18
+	undefined4 m_unk0x1c;             // 0x1c
+	undefined4 m_unk0x20;             // 0x20
+	IUnknown* m_unk0x24;              // 0x24
+	undefined4 m_unk0x28;             // 0x28
+	undefined4 m_unk0x2c;             // 0x2c
+	IUnknown* m_unk0x30;              // 0x30
+	undefined m_unk0x34;              // 0x34
+	undefined m_unk0x35;              // 0x35
+	undefined m_unk0x36[0x38 - 0x36]; // 0x36
+	undefined4 m_unk0x38;             // 0x38
+	ListHead m_unk0x3c;               // 0x3c
+	ListHead m_unk0x48;               // 0x48
+	undefined4 m_unk0x54;             // 0x54
+	undefined4 m_unk0x58;             // 0x58
+	ListHead m_unk0x5c;               // 0x5c
+	ListHead m_unk0x68;               // 0x68
+	ListHead m_unk0x74;               // 0x74
+	ListHead m_unk0x80;               // 0x80
+	ListHead m_unk0x8c;               // 0x8c
 };
 
 #endif // AMBERWOLF0X98_H

LEGORacers/include/crimsonforge0x800.h

@@ -0,0 +1,40 @@
+#ifndef CRIMSONFORGE0X800_H
+#define CRIMSONFORGE0X800_H
+
+#include "decomp.h"
+#include "tealpulse0x24.h"
+#include "types.h"
+
+// VTABLE: LEGORACERS 0x4af9a8
+// SIZE 0x800
+class CrimsonForge0x800 {
+public:
+	CrimsonForge0x800();
+	virtual void VTable0x00() = 0;                     // vtable+0x00
+	virtual ~CrimsonForge0x800();                      // vtable+0x04
+	virtual void VTable0x08();                         // vtable+0x08
+	virtual void VTable0x0c(LegoChar*, LegoChar*) = 0; // vtable+0x0c
+	virtual void VTable0x10() = 0;                     // vtable+0x10
+	virtual void VTable0x14() = 0;                     // vtable+0x14
+	virtual void VTable0x18() = 0;                     // vtable+0x18
+	virtual void VTable0x1c() = 0;                     // vtable+0x1c
+	virtual void VTable0x20() = 0;                     // vtable+0x20
+	virtual void VTable0x24() = 0;                     // vtable+0x24
+	virtual void VTable0x28();                         // vtable+0x28
+	virtual void VTable0x2c() = 0;                     // vtable+0x2c
+	virtual void VTable0x30() = 0;                     // vtable+0x30
+	virtual void VTable0x34() = 0;                     // vtable+0x34
+
+	// SYNTHETIC: LEGORACERS 0x4163b0
+	// CrimsonForge0x800::`scalar deleting destructor'
+
+	LegoU8 GetUnk0x04() { return m_unk0x04; }
+	TealPulse0x24& GetUnk0x7dc() { return m_unk0x7dc; }
+
+protected:
+	LegoU8 m_unk0x04;                  // 0x04
+	undefined m_unk0x05[0x7dc - 0x05]; // 0x05
+	TealPulse0x24 m_unk0x7dc;          // 0x7dc
+};
+
+#endif // CRIMSONFORGE0X800_H

LEGORacers/include/goldenoak0x128.h

@@ -28,11 +28,11 @@ class GoldenOak0x128 : public RubyHaze0x08, public ListLink {
 	// GoldenOak0x128::`scalar deleting destructor'
 
 private:
-	IndigoStar0x18* m_unk0x10;  // 0x10
-	ListHead m_unk0x14;         // 0x14
-	undefined m_unk0x20;        // 0x20
-	undefined m_unk0x21[0x103]; // 0x21
-	undefined4 m_unk0x124;      // 0x124
+	IndigoStar0x18* m_unk0x10;         // 0x10
+	ListHead m_unk0x14;                // 0x14
+	undefined m_unk0x20;               // 0x20
+	undefined m_unk0x21[0x124 - 0x21]; // 0x21
+	undefined4 m_unk0x124;             // 0x124
 };
 
 #endif // GOLDENOAK0X128_H

LEGORacers/include/ironflame0x944.h

@@ -1,30 +1,50 @@
 #ifndef IRONFLAME0X944_H
 #define IRONFLAME0X944_H
 
+#include "compat.h"
+#include "crimsonforge0x800.h"
 #include "decomp.h"
+#include "opalvault0xf0.h"
+#include "types.h"
 
 // VTABLE: LEGORACERS 0x4af9f4
 // SIZE 0x944
-class IronFlame0x944 {
+class IronFlame0x944 : public CrimsonForge0x800 {
 public:
-	virtual void VTable0x00(); // vtable+0x00
-	virtual ~IronFlame0x944(); // vtable+0x04
-	virtual void VTable0x08(); // vtable+0x08
-	virtual void VTable0x0c(); // vtable+0x0c
-	virtual void VTable0x10(); // vtable+0x10
-	virtual void VTable0x14(); // vtable+0x14
-	virtual void VTable0x18(); // vtable+0x18
-	virtual void VTable0x1c(); // vtable+0x1c
-	virtual void VTable0x20(); // vtable+0x20
-	virtual void VTable0x24(); // vtable+0x24
-	virtual void VTable0x28(); // vtable+0x28
-	virtual void VTable0x2c(); // vtable+0x2c
+	IronFlame0x944();
+	void VTable0x00() override;                     // vtable+0x00
+	~IronFlame0x944() override;                     // vtable+0x04
+	void VTable0x0c(LegoChar*, LegoChar*) override; // vtable+0x0c
+	void VTable0x10() override;                     // vtable+0x10
+	void VTable0x14() override;                     // vtable+0x14
+	void VTable0x18() override;                     // vtable+0x18
+	void VTable0x1c() override;                     // vtable+0x1c
+	void VTable0x20() override;                     // vtable+0x20
+	void VTable0x24() override;                     // vtable+0x24
+	void VTable0x28() override;                     // vtable+0x28
+	void VTable0x2c() override;                     // vtable+0x2c
+	void VTable0x30() override;                     // vtable+0x30
+	void VTable0x34() override;                     // vtable+0x34
 
 	// SYNTHETIC: LEGORACERS 0x416560
 	// IronFlame0x944::`scalar deleting destructor'
 
+	undefined4 GetUnk0x928() { return m_unk0x928; }
+	void SetUnk0x928(undefined4 p_unk0x928) { m_unk0x928 = p_unk0x928; }
+
 private:
-	undefined m_unk0x04[0x940]; // 0x04
+	undefined4 m_unk0x800;               // 0x800
+	undefined m_unk0x804[0x830 - 0x804]; // 0x804
+	undefined4 m_unk0x830;               // 0x830
+	OpalVault0xf0 m_unk0x834;            // 0x834
+	undefined4 m_unk0x924;               // 0x924
+	undefined4 m_unk0x928;               // 0x928
+	undefined4 m_unk0x92c;               // 0x92c
+	undefined4 m_unk0x930;               // 0x930
+	undefined4 m_unk0x934;               // 0x934
+	undefined4 m_unk0x938;               // 0x938
+	undefined4 m_unk0x93c;               // 0x93c
+	undefined4 m_unk0x940;               // 0x940
 };
 
 #endif // IRONFLAME0X944_H

LEGORacers/include/neoncactus0x1d6c.h

@@ -17,17 +17,20 @@ class NeonCactus0x1d6c : public CactusInterface0x4 {
 	// SYNTHETIC: LEGORACERS 0x42bb20
 	// NeonCactus0x1d6c::`scalar deleting destructor'
 
-	LegoS32 FUN_0042bbb0(LegoS32 p_argc, LegoChar** p_argv);
+	LegoS32 Init(LegoS32 p_argc, LegoChar** p_argv);
 	void FUN_0042bc20();
 	void FUN_0042bc40();
 	void FUN_0042bd00();
 	void FUN_0042be90();
+	LegoS32 FUN_0042bee0(LegoS32 p_argc, LegoChar** p_argv);
 
 private:
 	IronFlame0x944 m_unk0x04;             // 0x04
 	AmberWolf0x98 m_unk0x948;             // 0x948
 	CobaltMist0x30 m_unk0x9e0;            // 0x9e0
-	undefined m_unk0xa10[0x1d6c - 0xa10]; // 0xa10
+	undefined m_unk0xa10[0xa14 - 0xa10];  // 0xa10
+	undefined4 m_unk0xa14;                // 0xa14
+	undefined m_unk0xa18[0x1d6c - 0xa18]; // 0xa18
 };
 
 #endif // NEONCACTUS0X1D6C_H

LEGORacers/include/opalvault0xf0.h

@@ -0,0 +1,28 @@
+#ifndef OPALVAULT0XF0_H
+#define OPALVAULT0XF0_H
+
+#include "decomp.h"
+#include "types.h"
+
+// VTABLE: LEGORACERS 0x4b1224
+// SIZE 0xf0
+class OpalVault0xf0 {
+public:
+	OpalVault0xf0();
+	virtual void VTable0x00(); // vtable+0x00
+	virtual ~OpalVault0xf0();  // vtable+0x04
+	virtual void VTable0x08(); // vtable+0x08
+	virtual void VTable0x0c(); // vtable+0x0c
+	virtual void VTable0x10(); // vtable+0x10
+	virtual void VTable0x14(); // vtable+0x14
+	virtual void VTable0x18(); // vtable+0x18
+	virtual void VTable0x1c(); // vtable+0x1c
+
+	// SYNTHETIC: LEGORACERS 0x450350
+	// OpalVault0xf0::`scalar deleting destructor'
+
+private:
+	undefined m_unk0x04[0xf0 - 0x04]; // 0x04
+};
+
+#endif // OPALVAULT0XF0_H

LEGORacers/include/tealpulse0x24.h

@@ -0,0 +1,32 @@
+#ifndef TEALPULSE0X24_H
+#define TEALPULSE0X24_H
+
+#include "decomp.h"
+#include "types.h"
+
+// VTABLE: LEGORACERS 0x4b0f28
+// SIZE 0x24
+class TealPulse0x24 {
+public:
+	TealPulse0x24();
+	~TealPulse0x24();
+
+	virtual void VTable0x00();                                    // vtable+0x00
+	virtual undefined4* VTable0x04(undefined4*, const LegoChar*); // vtable+0x04
+	virtual void VTable0x08(undefined4, undefined4);              // vtable+0x08
+	virtual void VTable0x0c();                                    // vtable+0x0c
+
+	void FUN_0044c5a0();
+
+private:
+	undefined4 m_unk0x04; // 0x04
+	undefined4 m_unk0x08; // 0x08
+	undefined4 m_unk0x0c; // 0x0c
+	undefined4 m_unk0x10; // 0x10
+	undefined4 m_unk0x14; // 0x14
+	undefined4 m_unk0x18; // 0x18
+	undefined4 m_unk0x1c; // 0x1c
+	undefined m_unk0x20;  // 0x20
+};
+
+#endif // TEALPULSE0X24_H

LEGORacers/src/amberwolf0x98.cpp

@@ -9,6 +9,23 @@
 
 DECOMP_SIZE_ASSERT(AmberWolf0x98, 0x98)
 
+// FUNCTION: LEGORACERS 0x4185d0
+AmberWolf0x98::AmberWolf0x98()
+{
+	m_unk0x28 = 2;
+	m_unk0x34 = 2;
+	m_unk0x20 = 0;
+	m_unk0x1c = 0;
+	m_unk0x24 = NULL;
+	m_unk0x2c = 0;
+	m_unk0x30 = NULL;
+	m_unk0x38 = 22050;
+	m_unk0x35 = 16;
+	m_unk0x18 = 0;
+	m_unk0x58 = 0;
+	m_unk0x54 = 0;
+}
+
 // FUNCTION: LEGORACERS 0x4186a0
 AmberWolf0x98::~AmberWolf0x98()
 {