Improvements to tank bunker logic (#2266)

- Introduced alternate code paths for odd-sized foundations in relevant
places to allow odd-sized tank bunkers f.ex 3x3 ones.
- The logic to make vehicles enter center of building on even-sized
foundation hinges on function (`Force_Track()`) not implemented on all
locomotors and does not behave in visually consistent manner on
odd-sized foundations. Conversely the simpler approach with discrete
center cells present cannot be used with even-sized foundations.
- Non-Drive locomotors should hypothetically work better with the
discrete center cell approach but since there's no guarantee of parity I
have elected to not lift the hardcoded locomotor restrictions.
- Added customization for the logic update delay that can be used to
make tank bunkers more responsive on unit attempting to enter.
- Documentation with prior changes to tank bunker logic was consolidated
under single header since there's not a large amount of changes.

-------------------------------------

### Tank Bunker improvements

- `Bunker=true` and associated logic should now work more reliably on
odd-sized foundations. It still expects size on both X and Y axis to be
equal e.g `2x2` or `3x3` and will not behave correctly otherwise.
- It is now possible to change the tank bunker logic update delay by
setting `BunkerStateUpdateDelay`. Defaults to `[General]` ->
`BunkerStateUpdateDelay`. Lowering the value from the default value of
15 will make units trying to bunker up spend less time waiting.

In `rulesmd.ini`:
```ini
[General]
BunkerStateUpdateDelay=15  ; integer, game frames

[SOMEBUILDING]             ; BuildingType
BunkerStateUpdateDelay=    ; integer, game frames
```

Author: Starkku

CREDITS.md

@@ -299,6 +299,7 @@ This page lists all the individual contributions to the project by their author.
   - Building turret idle/firing/low power animations
   - Animation theater/tile palette toggle
   - Animatable template
+  - Tank Bunker improvements
 - **Morton (MortonPL)**:
   - `XDrawOffset` for animations
   - Shield passthrough & absorption

YRpp

@@ -1257,6 +1257,28 @@ IsAnimDelayedBurst=true            ; boolean
 The prism towers' fire is hardcoded to be delayed. Their fire will ignore this flag, just as they ignore `IsAnimDelayedFire`.
 ```
 
+### Tank Bunker improvements
+
+- `Bunker=true` and associated logic should now work more reliably on odd-sized foundations. It still expects size on both X and Y axis to be equal e.g `2x2` or `3x3` and will not behave correctly otherwise.
+- It is now possible to change the tank bunker logic update delay by setting `BunkerStateUpdateDelay`. Defaults to `[General]` -> `BunkerStateUpdateDelay`. Lowering the value from the default value of 15 will make units trying to bunker up spend less time waiting.
+- Setting `BunkerableAnyway=true` on a vehicle will bypass several otherwise hardcoded checks that would otherwise prevent it from being bunkerable - namely that it needs to have a turret, weapon and `SpeedType` other than `Hover`. It will still require `Bunkerable=true` and the vehicle to not be parasitized to allow bunkering.
+
+In `rulesmd.ini`:
+```ini
+[General]
+BunkerStateUpdateDelay=15  ; integer, game frames
+
+[SOMEBUILDING]             ; BuildingType
+BunkerStateUpdateDelay=    ; integer, game frames
+
+[SOMEVEHICLE]              ; VehicleType
+BunkerableAnyway=false     ; boolean
+```
+
+```{warning}
+Skipping the bunkerable checks doesn't mean that vehicles and tank bunkers will interact correctly - actual bunkerability is mainly determined by `Locomotor`. Details about locomotors' bunkerability can be found on [ModEnc](https://modenc.renegadeprojects.com/Bunkerable).
+```
+
 ### Unit repair customization
 
 - It is now possible to customize the repairing of units by `UnitRepair=true`, `UnitReload=true` and `Hospital=true` buildings.
@@ -2260,22 +2282,6 @@ Harvester.CanGuardArea=false                ; boolean
 Harvester.CanGuardArea.RequireTarget=false  ; boolean
 ```
 
-### Bunker entering check dehardcode
-
-- In vanilla, vehicles entering tank bunkers are subject to a series of hardcoding restrictions, including having to have turrets, having to have weapons, and not having Hover speed types. Now you can skip these restrictions.
-- This needs to be used with `Bunkerable=yes`.
-- This flag only skips the static check, that is, the check on the unit type. The dynamic check (cannot be parasitized) remains unchanged.
-
-In `rulesmd.ini`:
-```ini
-[SOMEVEHICLE]              ; VehicleType
-BunkerableAnyway=false     ; boolean
-```
-
-```{warning}
-Skipping checks with this feature doesn't mean that vehicles and tank bunkers will interact correctly. Following the simple checks performed by the provider of this feature, bunkerability is mainly determined by Locomotor. The details about locomotors' bunkerability can be found on [ModEnc](https://modenc.renegadeprojects.com/Bunkerable).
-```
-
 ### Custom Unit Crate Reroll Chance
 
 - It is possible to influence weighting of units given from crates (`CrateGoodie=true`) via `CrateGoodie.RerollChance`, which determines the chance that if this type of unit is rolled, it will reroll again for another type of unit.

docs/Fixed-or-Improved-Logics.md

@@ -397,7 +397,7 @@ HideShakeEffects=false           ; boolean
 - [Raise alert when technos are taking damage](New-or-Enhanced-Logics.md#raise-alert-when-technos-are-taking-damage) (by TaranDahl)
 - [Enhanced Bombard trajectory](New-or-Enhanced-Logics.md#bombard-trajectory) (by CrimRecya & Ollerus, based on knowledge of NaotoYuuki)
 - [Toggle waypoint for building](Fixed-or-Improved-Logics.md#waypoints-for-buildings) (by TaranDahl)
-- [Bunkerable checks dehardcode](Fixed-or-Improved-Logics.md#bunker-entering-check-dehardcode) (by TaranDahl)
+- [Bunkerable checks dehardcode](Fixed-or-Improved-Logics.md#tank-bunker-improvements) (by TaranDahl)
 - [No turret unit turn to the target](Fixed-or-Improved-Logics.md#unit-without-turret-always-turn-to-target) (by CrimRecya & TaranDahl)
 - [Damage multipliers](New-or-Enhanced-Logics.md#damage-multipliers) (by CrimRecya & Ollerus)
 - Customizable duration for electric bolts (by Starkku)
@@ -596,6 +596,7 @@ HideShakeEffects=false           ; boolean
 - [Allow infantry to perform type conversion when deploying and undeploying](New-or-Enhanced-Logics.md#allow-infantry-to-perform-type-conversion-when-deploying-and-undeploying) (by Noble_Fish)
 - Add `ClampToScreen` tag for `BannerType` (defaults to `true`) to control whether banner position is clamped to the visible area (by Chang_zhi)
 - [Customizable Berzerk mission](New-or-Enhanced-Logics.md#enhanced-berzerk-behavior) (by TaranDahl)
+- [Tank Bunker foundation and state update delay improvements](Fixed-or-Improved-Logics.md#tank-bunker-improvements) (by Starkku)
 
 #### Vanilla fixes:
 - Fixed sidebar not updating queued unit numbers when adding or removing units when the production is on hold (by CrimRecya)

docs/Whats-New.md

@@ -1170,3 +1170,133 @@ DEFINE_HOOK(0x44B6C7, BuildingClass_Mission_Attack_TurretAnim, 0x6)
 
 	return 0;
 }
+
+#pragma endregion
+
+#pragma region TankBunker
+
+// Jun 23, 2026 - Starkku: Vanilla tank bunker code assumes
+// even-sized foundation. The approach used for even-sized
+// foundations and those that have discrete center cell are
+// mutually exclusive due to pathfinding constraints.
+
+// Handle docking offset calculations.
+DEFINE_HOOK(0x447BE3, BuildingClass_DockingCoord_TankBunker, 0x6)
+{
+	enum { SkipGameCode = 0x447CE1 };
+
+	GET(BuildingClass*, pThis, ESI);
+
+	// Discrete center cell: Docking coord is building center instead of cell closest to approach.
+	if (pThis->Type->GetFoundationWidth() % 2)
+	{
+		const auto coords = pThis->GetCenterCoords();
+
+		// Cleaner hook return at function return is causing problems
+		// due to stack offsets, which is why we're doing it like this.
+		R->ECX(coords.X);
+		R->EDX(coords.Y);
+		R->EAX(&coords);
+
+		return SkipGameCode;
+	}
+
+	return 0;
+}
+
+// Remove now unnecessary (and in fact interfering) rotation code in BuildingClass::UpdateTankBunker().
+DEFINE_HOOK(0x459069, BuildingClass_UpdateTankBunker_CheckOccupants, 0x7)
+{
+	enum { SkipGameCode = 0x4590EF };
+
+	GET(BuildingClass*, pThis, ESI);
+
+	// Discrete center cell: No need to change facing at this stage.
+	if (pThis->Type->GetFoundationWidth() % 2)
+		return SkipGameCode;
+
+	return 0;
+}
+
+// Handle force moving unit to center of bunker.
+DEFINE_HOOK(0x459101, BuildingClass_UpdateTankBunker_RotateToTrack, 0x6)
+{
+	enum { ReturnFromFunction = 0x4591CE };
+
+	GET(BuildingClass*, pThis, ESI);
+	GET(UnitClass*, pUnit, EBP);
+
+	// Discrete center cell: Skip straight to rotating in bunker once finished moving instead of forcing track to center.
+	if (pThis->Type->GetFoundationWidth() % 2)
+	{
+		if (!pUnit->Locomotor->Is_Moving())
+		{
+			pUnit->PrimaryFacing.SetDesired(DirStruct(DirType::South));
+			pThis->TankBunkerState = TankBunkerState::RotateInBunker;
+		}
+
+		return ReturnFromFunction;
+	}
+
+	return 0;
+}
+
+inline void EjectBunkeredUnit(BuildingClass* pThis, UnitClass* pUnit)
+{
+	auto const pType = pUnit->Type;
+	auto const cell = pThis->GetMapCoords() + CellStruct(-1, 1);
+	auto const pNearbyCell = MapClass::Instance.NearByLocation(cell, pType->SpeedType, -1, pType->MovementZone, false, 1, 1, false, false, false, true, cell, false, false);
+	pUnit->SetDestination(MapClass::Instance.GetCellAt(pNearbyCell), false);
+	pUnit->QueueMission(Mission::Move, false);
+}
+
+// Bunker was destroyed, sold or warped away.
+DEFINE_HOOK(0x4593C7, BuildingClass_DestroyTankBunker, 0x6)
+{
+	enum { SkipGameCode = 0x459450 };
+
+	GET(BuildingClass*, pThis, EDI);
+	GET(UnitClass*, pUnit, ESI);
+
+	// Discrete center cell: Send unit out to a nearby cell without forcing drive track.
+	if (pThis->Type->GetFoundationWidth() % 2)
+	{
+		EjectBunkeredUnit(pThis, pUnit);
+		return SkipGameCode;
+	}
+
+	return 0;
+}
+
+// Manual unload of the bunker.
+DEFINE_HOOK(0x4596EC, BuildingClass_UnloadTankBunker, 0x6)
+{
+	enum { SkipGameCode = 0x45980D };
+
+	GET(BuildingClass*, pThis, EDI);
+	GET(UnitClass*, pUnit, ESI);
+
+	// Discrete center cell: Send unit out to a nearby cell without forcing drive track.
+	if (pThis->Type->GetFoundationWidth() % 2)
+	{
+		EjectBunkeredUnit(pThis, pUnit);
+		return SkipGameCode;
+	}
+
+	return 0;
+}
+
+// Add customization for tank bunker logic update delay.
+DEFINE_HOOK(0x44C976, BuildingClass_Mission_Repair_TankBunker, 0x5)
+{
+	GET(BuildingClass*, pThis, EBP);
+
+	auto const pType = pThis->Type;
+
+	if (pType->Bunker && (pThis->TankBunkerState > TankBunkerState::Idle && pThis->TankBunkerState < TankBunkerState::Bunkered))
+		R->EAX(BuildingTypeExt::ExtMap.Find(pType)->BunkerStateUpdateDelay.Get(RulesExt::Global()->BunkerStateUpdateDelay));
+
+	return 0;
+}
+
+#pragma endregion

src/Ext/Building/Hooks.cpp

@@ -228,6 +228,7 @@ void BuildingTypeExt::ExtData::LoadFromINIFile(CCINIClass* const pINI)
 	this->BuildingBunkerROFMult.Read(exINI, pSection, "BunkerROFMultMultiplier");
 	this->BunkerWallsUpSound.Read(exINI, pSection, "BunkerWallsUpSound");
 	this->BunkerWallsDownSound.Read(exINI, pSection, "BunkerWallsDownSound");
+	this->BunkerStateUpdateDelay.Read(exINI, pSection, "BunkerStateUpdateDelay");
 	this->BuildingRepairedSound.Read(exINI, pSection, "BuildingRepairedSound");
 	this->Refinery_UseStorage.Read(exINI, pSection, "Refinery.UseStorage");
 	this->UndeploysInto_Sellable.Read(exINI, pSection, "UndeploysInto.Sellable");
@@ -404,6 +405,7 @@ void BuildingTypeExt::ExtData::Serialize(T& Stm)
 		.Process(this->BuildingBunkerROFMult)
 		.Process(this->BunkerWallsUpSound)
 		.Process(this->BunkerWallsDownSound)
+		.Process(this->BunkerStateUpdateDelay)
 		.Process(this->BuildingRepairedSound)
 		.Process(this->Refinery_UseNormalActiveAnim)
 		.Process(this->HasPowerUpAnim)

src/Ext/BuildingType/Body.cpp

@@ -94,6 +94,7 @@ class BuildingTypeExt
 		Nullable<float> BuildingBunkerROFMult;
 		NullableIdx<VocClass> BunkerWallsUpSound;
 		NullableIdx<VocClass> BunkerWallsDownSound;
+		Nullable<int> BunkerStateUpdateDelay;
 
 		NullableIdx<VocClass> BuildingRepairedSound;
 
@@ -189,6 +190,7 @@ class BuildingTypeExt
 			, BuildingBunkerROFMult {}
 			, BunkerWallsUpSound {}
 			, BunkerWallsDownSound {}
+			, BunkerStateUpdateDelay {}
 			, BuildingRepairedSound {}
 			, Refinery_UseNormalActiveAnim { false }
 			, HasPowerUpAnim {}

src/Ext/BuildingType/Body.h

@@ -434,6 +434,8 @@ void RulesExt::ExtData::LoadBeforeTypeData(RulesClass* pThis, CCINIClass* pINI)
 
 	this->TeamDelays_DynamicType.Read(exINI, GameStrings::General, "TeamDelays.DynamicType");
 
+	this->BunkerStateUpdateDelay.Read(exINI, GameStrings::General, "BunkerStateUpdateDelay");
+
 	char tempBuffer[40];
 	for (size_t i = 0; i < 8; i++)
 	{
@@ -787,6 +789,7 @@ void RulesExt::ExtData::Serialize(T& Stm)
 		.Process(this->TeamDelays_DynamicType)
 		.Process(this->TeamDelays_Count)
 		.Process(this->BerzerkMission)
+		.Process(this->BunkerStateUpdateDelay)
 		;
 }
 

src/Ext/Rules/Body.cpp

@@ -374,6 +374,8 @@ class RulesExt
 
 		Valueable<Mission> BerzerkMission;
 
+		Valueable<int> BunkerStateUpdateDelay;
+
 		ExtData(RulesClass* OwnerObject) : Extension<RulesClass>(OwnerObject)
 			, Storage_TiberiumIndex { -1 }
 			, HarvesterDumpAmount { 0.0f }
@@ -685,6 +687,8 @@ class RulesExt
 			, TeamDelays_DynamicType { DynamicTeamDelayType::StartingPoint }
 			, TeamDelays_Count {}
 			, BerzerkMission { Mission::Hunt }
+
+			, BunkerStateUpdateDelay { 15 }
 		{ }
 
 		virtual ~ExtData() = default;