Rework the extension system into a mirror class hierarchy

.github/copilot-instructions.md

@@ -92,10 +92,12 @@ scripts/                Build and setup scripts
 ### Extending a vanilla game class
 
 Each extension lives in `src/Ext/<ClassName>/` with:
-- **`Body.h`**: Declares `<Name>Ext` with `ExtData` (inherits `Extension<T>`) and `ExtContainer`/`ExtMap`.
+- **`Body.h`**: Declares `<Name>Ext`, part of an inheritance hierarchy mirroring the game's own class tree rooted at `AbstractExt` (`Container.h`); concrete leaf classes also declare an `ExtContainer`/`ExtMap` (inherits `Container<T>`).
 - **`Body.cpp`**: Implements constructor, `LoadFromINIFile`, serialization (`Serialize`), and common hooks.
 - **`Hooks.cpp` / `Hooks.*.cpp`**: `DEFINE_HOOK(address, Name, size)` macros for Syringe code injection.
 
+Look extensions up only through the typed static accessors available at every level of the hierarchy: `<Name>Ext::Fetch(pThis)` (fatals if the object has no extension attached) or `<Name>Ext::TryFetch(pThis)` (returns null instead — also the right choice while a savegame is loading). The container lookups `ExtMap.Find`/`ExtMap.TryFind` are deprecated compatibility forwards, as is each pre-rework class's `ExtData` alias (the extension class itself replaced the old nested data class); `ExtMap`'s remaining role is lifecycle and persistence machinery (`Allocate`/`Remove`/`LoadFromINI` plus the centralized streaming driven from `Phobos.Ext.cpp`).
+
 After creating a new extension class, **always register it** in `src/Phobos.Ext.cpp` inside the `PhobosTypeRegistry` alias (the `using PhobosTypeRegistry = TypeRegistry<...>` declaration).
 
 ### Adding a new enumerable type

CREDITS.md

@@ -586,6 +586,7 @@ This page lists all the individual contributions to the project by their author.
   - Replace `BLOWFISH.DLL` using Red Alert source code
   - Adjust the dehardcoding of the 255 `OverlayType` limit to a different format
   - Voxel drawing invisible sections skip
+  - Extension system rework
 - **CrimRecya**:
   - Fix `LimboKill` not working reliably
   - Allow using waypoints, area guard and attack move with aircraft

Phobos.vcxproj

@@ -3,6 +3,21 @@
   <PropertyGroup>
     <ShowAllFiles>true</ShowAllFiles>
   </PropertyGroup>
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">
+    <ClCompile>
+      <MultiProcessorCompilation>true</MultiProcessorCompilation>
+    </ClCompile>
+  </ItemDefinitionGroup>
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='DevBuild|Win32'">
+    <ClCompile>
+      <MultiProcessorCompilation>true</MultiProcessorCompilation>
+    </ClCompile>
+  </ItemDefinitionGroup>
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">
+    <ClCompile>
+      <MultiProcessorCompilation>true</MultiProcessorCompilation>
+    </ClCompile>
+  </ItemDefinitionGroup>
   <PropertyGroup Label="Globals">
     <ProjectName>Phobos</ProjectName>
     <RootNamespace>Phobos</RootNamespace>
@@ -61,6 +76,11 @@
     <ClCompile Include="src\Ext\Beacon\Hooks.cpp" />
     <!-- src\Ext\Building -->
     <ClCompile Include="src\Ext\Building\Body.cpp" />
+    <ClCompile Include="src\Ext\Unit\Body.cpp" />
+    <ClCompile Include="src\Ext\Infantry\Body.cpp" />
+    <ClCompile Include="src\Ext\UnitType\Body.cpp" />
+    <ClCompile Include="src\Ext\InfantryType\Body.cpp" />
+    <ClCompile Include="src\Ext\AircraftType\Body.cpp" />
     <ClCompile Include="src\Ext\Building\Hooks.cpp" />
     <ClCompile Include="src\Ext\Building\Hooks.Grinding.cpp" />
     <ClCompile Include="src\Ext\Building\Hooks.Production.cpp" />
@@ -277,6 +297,7 @@
     <ClCompile Include="src\Utilities\AresHelper.cpp" />
     <ClCompile Include="src\Utilities\Constructs.cpp" />
     <ClCompile Include="src\Utilities\Debug.cpp" />
+    <ClCompile Include="src\Utilities\Detach.cpp" />
     <ClCompile Include="src\Utilities\EnumFunctions.cpp" />
     <ClCompile Include="src\Utilities\GeneralUtils.cpp" />
     <ClCompile Include="src\Utilities\Patch.cpp" />
@@ -317,6 +338,17 @@
     <ClInclude Include="src\Ext\Anim\Body.h" />
     <ClInclude Include="src\Ext\AnimType\Body.h" />
     <ClInclude Include="src\Ext\Building\Body.h" />
+    <ClInclude Include="src\Ext\Object\Body.h" />
+    <ClInclude Include="src\Ext\Mission\Body.h" />
+    <ClInclude Include="src\Ext\Radio\Body.h" />
+    <ClInclude Include="src\Ext\Foot\Body.h" />
+    <ClInclude Include="src\Ext\AbstractType\Body.h" />
+    <ClInclude Include="src\Ext\ObjectType\Body.h" />
+    <ClInclude Include="src\Ext\Unit\Body.h" />
+    <ClInclude Include="src\Ext\Infantry\Body.h" />
+    <ClInclude Include="src\Ext\UnitType\Body.h" />
+    <ClInclude Include="src\Ext\InfantryType\Body.h" />
+    <ClInclude Include="src\Ext\AircraftType\Body.h" />
     <ClInclude Include="src\Ext\BuildingType\Body.h" />
     <ClInclude Include="src\Ext\Bullet\Body.h" />
     <ClInclude Include="src\Ext\Bullet\Trajectories\BombardTrajectory.h" />
@@ -403,6 +435,7 @@
     <ClInclude Include="src\Utilities\AresHelper.h" />
     <ClInclude Include="src\Utilities\Interpolation.h" />
     <ClInclude Include="src\Utilities\Constructs.h" />
+    <ClInclude Include="src\Utilities\Detach.h" />
     <ClInclude Include="src\Utilities\Container.h" />
     <ClInclude Include="src\Utilities\Debug.h" />
     <ClInclude Include="src\Utilities\Enum.h" />
@@ -424,4 +457,4 @@
     <ClInclude Include="src\Utilities\Template.h" />
     <ClInclude Include="src\Utilities\TemplateDef.h" />
   </ItemGroup>
-</Project>
+</Project>

docs/Project-guidelines-and-policies.md

@@ -75,12 +75,13 @@ Assuming you've successfully cloned and built the project before getting here, y
   - `New/` - source code for new ingame classes.
     - `Type/` - new enumerated types (types that are declared with a list section in an INI, for example, radiation types) implemented in the project. Every enumerated type class inherits `Enumerable<T>` (where `T` is an enum. type class) class that is defined in `Enumerable.h`.
     - `Entity/` - classes that represent ingame entities are located here.
-  - `Ext/` - source code for vanilla engine class extensions. Each class extension is kept in a separate folder named after vanilla engine class name and contains the following:
-    - `Body.h` and `Body.cpp` contain class and method definitions/declarations and common extension hooks. Each extension class must contain the following to work correctly:
-      - `ExtData` - extension data class definition which inherits `Extension<T>` from `Container.h` (where `T` is the class that is being extended), which is the actual class that contains new data for vanilla classes;
-      - `ExtContainer` - a definition of a special map class to store and look up `ExtData` instances for base class instances which inherits `Container<T>` from `Container.h` (where `T` is the extension data class);
-      - `ExtMap` - a static instance of `ExtContainer` map;
-      - constructor, destructor, serialization, deserialization and (for appropriate classes) INI reading hooks.
+  - `Ext/` - source code for vanilla engine class extensions. Extension classes form a parallel inheritance hierarchy mirroring the game's own class tree (`AbstractExt` from `Container.h` is the root; e.g. `BuildingExt : TechnoExt : RadioExt : MissionExt : ObjectExt : AbstractExt`), and every game object carries exactly one extension instance of the most derived matching type, cached inside the object at the unified `AbstractClass` `0x18` slot. Each class extension is kept in a separate folder named after vanilla engine class name and contains the following:
+    - `Body.h` and `Body.cpp` contain class and method definitions/declarations and common extension hooks. Each extension class contains the following to work correctly:
+      - new data members and (for appropriate classes) `LoadFromINIFile`/`SaveToStream`/`LoadFromStream` overrides, plus static helper methods;
+      - `ExtContainer`/`ExtMap` - the per-class container (inherits `Container<T>` from `Container.h`) that tracks all live instances of one concrete extension class for bulk operations (allocation/removal, centralized savegame streaming, post-load relinking, scenario clearing); only concrete leaf classes (e.g. `BuildingExt`) have containers, while every level of the hierarchy provides typed `Fetch`/`TryFetch`. The container's own `Find`/`TryFind` lookups are deprecated compatibility forwards (`TechnoExt`/`TechnoTypeExt`, whose containers were split into per-leaf ones, keep a lookup-only `ExtMap` stand-in for the same reason), and every pre-rework class carries a deprecated `ExtData` alias of itself so code written against the old nested data classes keeps compiling;
+      - `Fetch`/`TryFetch` statics - the O(1) lookup used at call sites (`TechnoExt::Fetch(pThis)`); `Fetch` fatals if the object carries no extension, `TryFetch` returns null instead (also the right choice while a savegame is loading);
+      - constructor/destructor and (for appropriate classes) INI reading hooks. Serialization is centralized in `Phobos.Ext.cpp` - there are no per-class savegame hooks. The one exception is `CellExt`: the game treats cells as value objects with unstable identity (it re-initializes them in place and copies them around wholesale), so cell extensions are persisted inline within each cell's own savegame block instead (see `Ext/Cell/Body.cpp`).
+    - Extensions subscribe to pointer invalidation by inheriting `Detach::Listener<T>` from `Utilities/Detach.h` and overriding `OnDetach` (see `HouseExt` for an example).
     - `Hooks.cpp` and `Hooks.*.cpp` contain non-common hooks to correctly patch in new custom logics.
   - `ExtraHeaders/` - extra header files to interact with / describe types included in game binary that are not included in YRpp yet.
   - `Misc/` - uncategorized source code, including hooks that don't belong to an extension class.
@@ -197,7 +198,7 @@ if (SomeCondition())
 - A space must be put between braces of empty curly brace blocks.
 - To have less Git merge conflicts member initializer lists and other list-like syntax structures used in frequently modified places should be split per-item with item separation characters (commas, for example) placed *after newline character*:
 ```cpp
-ExtData(TerrainTypeClass* OwnerObject) : Extension<TerrainTypeClass>(OwnerObject)
+TerrainTypeExt(TerrainTypeClass* OwnerObject) : ObjectTypeExt(OwnerObject)
     , SpawnsTiberium_Type(0)
     , SpawnsTiberium_Range(1)
     , SpawnsTiberium_GrowthStage({ 3, 0 })

docs/Whats-New.md

@@ -52,6 +52,7 @@ This serves as a changelog for when you just need to drop the new version in wit
   - `[WarheadType] -> KillWeapon.OnFirer.AffectsHouses` -> `[WarheadType] -> KillWeapon.OnFirer.AffectsHouse`
   - `[WarheadType/SuperWeaponType] -> Convert(N).AffectedHouses` -> `[WarheadType/SuperWeaponType] -> Convert(N).AffectsHouse`
   - `[SuperWeaponType] -> LimboKill.Affected` -> `[SuperWeaponType] -> LimboKill.AffectsHouse`
+- The extension system has been reworked to follow the game's own class model. Savegames made with earlier Phobos builds are incompatible with this version.
 
 ```{note}
 - If it is detected that you are using the old INI flags, a warning will be outputted to `debug.log`.
@@ -614,6 +615,7 @@ HideShakeEffects=false           ; boolean
 - [RA1-Style Multi-Turret and Multi-Barrel](New-or-Enhanced-Logics.md#ra1-style-multi-turret-and-multi-barrel) (by TaranDahl & CrimRecya)
 - [Allow Laser drawing position update](New-or-Enhanced-Logics.md#allow-laser-drawing-position-update) (by Noble_Fish)
 - Customize the distance for `NoQueueUpToEnter` transport units to board passengers (by Noble_Fish)
+- Reworked the extension system internals to form a class hierarchy mirroring the game's own, with centralized savegame serialization (by ZivDero)
 
 #### Vanilla fixes:
 - Fixed sidebar not updating queued unit numbers when adding or removing units when the production is on hold (by CrimRecya)

src/Commands/NextIdleHarvester.cpp

@@ -43,7 +43,7 @@ void NextIdleHarvesterCommandClass::Execute(WWKey eInput) const
 	{
 		if (auto const pTechno = abstract_cast<TechnoClass*>(pNextObject))
 		{
-			auto const pTypeExt = TechnoExt::ExtMap.Find(pTechno)->TypeExtData;
+			auto const pTypeExt = TechnoExt::Fetch(pTechno)->TypeExtData;
 
 			if (pTypeExt->Harvester_Counted && !TechnoExt::IsHarvesting(pTechno))
 			{

src/Commands/ObjectInfo.cpp

@@ -133,7 +133,7 @@ void ObjectInfoCommandClass::Execute(WWKey eInput) const
 
 		append("Current HP = (%d / %d)", pFoot->Health, pType->Strength);
 
-		auto const pTechnoExt = TechnoExt::ExtMap.Find(pFoot);
+		auto const pTechnoExt = TechnoExt::Fetch(pFoot);
 		auto const pShieldData = pTechnoExt->Shield.get();
 
 		if (pTechnoExt->CurrentShieldType && pShieldData)
@@ -202,7 +202,7 @@ void ObjectInfoCommandClass::Execute(WWKey eInput) const
 
 		append("Current HP = (%d / %d)\n", pBuilding->Health, pBuilding->Type->Strength);
 
-		auto const pTechnoExt = TechnoExt::ExtMap.Find(pBuilding);
+		auto const pTechnoExt = TechnoExt::Fetch(pBuilding);
 		auto const pShieldData = pTechnoExt->Shield.get();
 
 		if (pTechnoExt->CurrentShieldType && pShieldData)

src/Ext/AbstractType/Body.h

@@ -0,0 +1,27 @@
+#pragma once
+
+#include <AbstractTypeClass.h>
+#include <Utilities/Container.h>
+
+// Empty intermediate base mirroring AbstractTypeClass in the extension hierarchy.
+class AbstractTypeExt : public AbstractExt
+{
+public:
+	explicit AbstractTypeExt(AbstractTypeClass* const OwnerObject) : AbstractExt(OwnerObject)
+	{ }
+
+	AbstractTypeClass* OwnerObject() const
+	{
+		return static_cast<AbstractTypeClass*>(this->GetAttachedObject());
+	}
+
+	static AbstractTypeExt* Fetch(const AbstractTypeClass* pThis)
+	{
+		return AbstractExt::Fetch<AbstractTypeExt>(pThis);
+	}
+
+	static AbstractTypeExt* TryFetch(const AbstractTypeClass* pThis)
+	{
+		return AbstractExt::TryFetch<AbstractTypeExt>(pThis);
+	}
+};

src/Ext/Aircraft/Body.cpp

@@ -3,14 +3,14 @@
 #include <Ext/BuildingType/Body.h>
 #include <Ext/WeaponType/Body.h>
 
-// TODO: Implement proper extended AircraftClass.
+AircraftExt::ExtContainer AircraftExt::ExtMap;
 
 void AircraftExt::FireWeapon(AircraftClass* pThis, AbstractClass* pTarget)
 {
-	auto const pExt = TechnoExt::ExtMap.Find(pThis);
+	auto const pExt = TechnoExt::Fetch(pThis);
 	const int weaponIndex = pExt->CurrentAircraftWeaponIndex;
 	auto const pWeapon = pThis->GetWeapon(weaponIndex)->WeaponType;
-	auto const pWeaponExt = WeaponTypeExt::ExtMap.Find(pWeapon);
+	auto const pWeaponExt = WeaponTypeExt::Fetch(pWeapon);
 	const int burstCount = pWeapon->Burst;
 	const bool isStrafe = pThis->Is_Strafe();
 
@@ -51,7 +51,7 @@ void AircraftExt::FireWeapon(AircraftClass* pThis, AbstractClass* pTarget)
 bool AircraftExt::PlaceReinforcementAircraft(AircraftClass* pThis, CoordStruct edgeCoords)
 {
 	auto const pType = pThis->Type;
-	auto const pTypeExt = TechnoTypeExt::ExtMap.Find(pType);
+	auto const pTypeExt = TechnoTypeExt::Fetch(pType);
 	auto dir = DirType::North;
 	auto coords = edgeCoords;
 	coords.Z = 0;
@@ -83,7 +83,7 @@ bool AircraftExt::PlaceReinforcementAircraft(AircraftClass* pThis, CoordStruct e
 
 CellStruct AircraftExt::PickEdgeCellForPlane(AircraftTypeClass* pPlaneType, CellStruct destCell, Edge edge, bool isOnRetreat)
 {
-	auto const pTypeExt = TechnoTypeExt::ExtMap.Find(pPlaneType);
+	auto const pTypeExt = TechnoTypeExt::Fetch(pPlaneType);
 	auto const edgeMode = !isOnRetreat ? pTypeExt->SpawnFromEdge : pTypeExt->RetreatToEdge;
 	auto spawnEdge = edge;
 	auto refCell = CellStruct::Empty;
@@ -143,7 +143,7 @@ DirType AircraftExt::GetLandingDir(AircraftClass* pThis, BuildingClass* pDock)
 		if (auto const pBuilding = pDock ? pDock : abstract_cast<BuildingClass*, true>(pLink))
 		{
 			auto const pBuildingType = pBuilding->Type;
-			auto const pBuildingTypeExt = BuildingTypeExt::ExtMap.Find(pBuildingType);
+			auto const pBuildingTypeExt = BuildingTypeExt::Fetch(pBuildingType);
 			const int docks = pBuildingType->NumberOfDocks;
 			const int linkIndex = pBuilding->FindLinkIndex(pThis);
 
@@ -159,10 +159,40 @@ DirType AircraftExt::GetLandingDir(AircraftClass* pThis, BuildingClass* pDock)
 			return pLink->PrimaryFacing.Current().GetDir();
 	}
 
-	const int landingDir = TechnoTypeExt::ExtMap.Find(pType)->LandingDir.Get((int)poseDir);
+	const int landingDir = TechnoTypeExt::Fetch(pType)->LandingDir.Get((int)poseDir);
 
 	if (!pType->AirportBound && landingDir < 0)
 		return pThis->PrimaryFacing.Current().GetDir();
 
 	return static_cast<DirType>(std::clamp(landingDir, 0, 255));
 }
+
+// =============================
+// container
+
+AircraftExt::ExtContainer::ExtContainer() : Container("AircraftClass") { }
+AircraftExt::ExtContainer::~ExtContainer() = default;
+
+// =============================
+// container hooks
+
+DEFINE_HOOK(0x413D30, AircraftClass_CTOR, 0x7)
+{
+	GET(AircraftClass*, pItem, ESI);
+
+	AircraftExt::ExtMap.Allocate(pItem);
+
+	return 0;
+}
+
+// Late in every destructor body of the class, right before it chains into the
+// base destructor: the last point where the extension is no longer used.
+DEFINE_HOOK_AGAIN(0x41426D, AircraftClass_DTOR, 0x9)
+DEFINE_HOOK(0x4141FA, AircraftClass_DTOR, 0x9)
+{
+	GET(AircraftClass*, pItem, EDI);
+
+	AircraftExt::ExtMap.Remove(pItem);
+
+	return 0;
+}

src/Ext/Aircraft/Body.h

@@ -1,13 +1,45 @@
 #pragma once
 #include <Ext/Techno/Body.h>
+#include <Ext/Foot/Body.h>
+#include <AircraftClass.h>
 
-// TODO: Implement proper extended AircraftClass.
-
-class AircraftExt
+// Concrete leaf extension for AircraftClass (empty; techno data lives in TechnoExt).
+class AircraftExt final : public FootExt
 {
 public:
+	using base_type = AircraftClass;
+
+	static constexpr DWORD Canary = 0xA1A2A3A4;
+
+	explicit AircraftExt(AircraftClass* const OwnerObject) : FootExt(OwnerObject)
+	{ }
+
+	AircraftClass* OwnerObject() const
+	{
+		return static_cast<AircraftClass*>(this->GetAttachedObject());
+	}
+
 	static void FireWeapon(AircraftClass* pThis, AbstractClass* pTarget);
 	static bool PlaceReinforcementAircraft(AircraftClass* pThis, CoordStruct edgeCoords);
 	static CellStruct PickEdgeCellForPlane(AircraftTypeClass* pPlaneType, CellStruct destCell, Edge edge, bool isOnRetreat = false);
 	static DirType GetLandingDir(AircraftClass* pThis, BuildingClass* pDock = nullptr);
+
+	class ExtContainer final : public Container<AircraftExt>
+	{
+	public:
+		ExtContainer();
+		~ExtContainer();
+	};
+
+	static ExtContainer ExtMap;
+
+	static AircraftExt* Fetch(const AircraftClass* pThis)
+	{
+		return AbstractExt::Fetch<AircraftExt>(pThis);
+	}
+
+	static AircraftExt* TryFetch(const AircraftClass* pThis)
+	{
+		return AbstractExt::TryFetch<AircraftExt>(pThis);
+	}
 };