Add additional draw offset logic for attached and AE animations

- Also optimize AE animation drawing logic update

Author: Starkku

CREDITS.md

@@ -292,6 +292,7 @@ This page lists all the individual contributions to the project by their author.
   - Fix vehicles disguised as trees incorrectly displaying veterancy insignia when they shouldn't
   - GapGen + SpySat desync fix
   - Frame CRC generation rewrite
+  - Attached animation draw offset customizations
 - **Morton (MortonPL)**:
   - `XDrawOffset` for animations
   - Shield passthrough & absorption

docs/Fixed-or-Improved-Logics.md

@@ -52,7 +52,6 @@ This page describes all ingame logics that are fixed or improved in Phobos witho
 
 - Vehicle to building deployers now keep their target when deploying with `DeployToFire`.
 - Effects like lasers are no longer drawn from wrong firing offset on weapons that use Burst.
-- Animations can now be offset on the X axis with `XDrawOffset`.
 - `IsSimpleDeployer` units now only play `DeploySound` and `UndeploySound` once, when done with (un)deploying instead of repeating it over duration of turning and/or `DeployingAnim`.
 - AITrigger can now recognize Building Upgrades as legal condition.
 - `EWGates` and `NSGates` now will link walls like `xxGateOne` and `xxGateTwo` do.
@@ -889,6 +888,23 @@ In `artmd.ini`:
 Crater.DestroyTiberium=         ; boolean, default to [General] -> AnimCraterDestroyTiberium
 ```
 
+### Draw offset customization
+
+- `XDrawOffset` can be used to adjust horizontal/X axis position of the animation.
+- `YDrawOffset.ApplyBracketHeight` makes Y axis position follow it's owner object's selection bracket height (for buildings, this is based on `Height` and `Foundation`, for others it is influenced by `PixelSelectionBracketDelta`) if it is attached to one.
+  - By default this will only apply if the bracket position is negative e.g it is moved upwards from the object center. If `YDrawOffset.InvertBracketShift` is set to true, the opposite is true and negative shift is ignored.
+  - The bracket-based shift can be further adjusted with offset from `YDrawOffset.BracketAdjust`, overridden by `YDrawOffset.BracketAdjust.Buildings` for buildings only.
+ 
+In `artmd.ini`:
+```ini
+[SOMEANIM]                            ; AnimationType
+XDrawOffset=0,0                       ; X,Y, pixels relative to default
+YDrawOffset.ApplyBracketHeight=false  ; boolean
+YDrawOffset.InvertBracketShift=false  ; boolean
+YDrawOffset.BracketAdjust=0,0         ; X,Y, pixels relative to default
+YDrawOffset.BracketAdjust.Buildings=  ; X,Y, pixels relative to default
+```
+
 ### Fire animations spawned by Scorch & Flamer
 
 - Tiberian Sun allowed `Scorch=true` and `Flamer=true` animations to spawn fire animations from `[AudioVisual] -> SmallFire` & `LargeFire`. This behaviour has been reimplemented and is fully customizable.

docs/New-or-Enhanced-Logics.md

@@ -31,6 +31,8 @@ This page describes all the engine features that are either new and introduced b
     - `Animation.TemporalAction` determines what happens to the animation when the attached object is under effect of `Temporal=true` Warhead.
     - `Animation.UseInvokerAsOwner` can be used to set the house and TechnoType that created the effect (e.g firer of the weapon that applied it) as the animation's owner & invoker instead of the object the effect is attached to.
     - `Animation.HideIfAttachedWith` contains list of other AttachEffectTypes that if attached to same techno as the current one, will hide this effect's animation.
+    - `Animation.DrawOffsetN` (where N is integer starting from 0) can be used to define draw offset rules for the animation. These are parsed starting from index 0 until offset with value 0,0 is encountered.
+      - `Animation.DrawOffsetN.RequiredTypes` contains list other AttachEffectTypes that need to be attached on the same techno as the current one for the draw offset rule to apply. Note that this does not currently work correctly together with `Animation.HideIfAttachedWith`, animations hidden by this may not cause drawing offset rules to be updated even if they should.
   - `CumulativeAnimations` can be used to declare a list of animations used for `Cumulative=true` types instead of `Animation`. An animation is picked from the list in order matching the number of active instances of the type on the object, with last listed animation used if number is higher than the number of listed animations. This animation is only displayed once and is transferred from the effect to another of same type (specifically one with longest remaining duration), if such exists, upon expiration or removal. Note that because `Cumulative.MaxCount` limits the number of effects of same type that can be applied this can cause animations to 'flicker' here as effects expire before new ones can be applied in some circumstances.
     - `CumulativeAnimations.RestartOnChange` determines if the animation playback is restarted when the type of animation changes, if not then playback resumes at frame at same position relative to the animation's length.
   - Attached effect can fire off a weapon when expired / removed / object dies by setting `ExpireWeapon`.
@@ -110,6 +112,8 @@ Animation.OfflineAction=Hides                      ; AttachedAnimFlag (None, Hid
 Animation.TemporalAction=None                      ; AttachedAnimFlag (None, Hides, Temporal, Paused or PausedTemporal)
 Animation.UseInvokerAsOwner=false                  ; boolean
 Animation.HideIfAttachedWith=                      ; List of AttachEffectTypes
+Animation.DrawOffsetN=0,0                          ; X,Y, pixels relative to default
+Animation.DrawOffsetN.RequiredTypes=               ; List of AttachEffectTypes
 CumulativeAnimations=                              ; List of AnimationTypes
 CumulativeAnimations.RestartOnChange=true          ; boolean
 ExpireWeapon=                                      ; WeaponType

docs/Whats-New.md

@@ -576,6 +576,8 @@ New:
 - Customize `HarvesterLoadRate` (by Noble_Fish)
 - [Toggle to prevent `ShrapnelWeapon` from targeting buildings multiple times](Fixed-or-Improved-Logics.md#shrapnel-enhancements) (by Starkku)
 - [Laser drawing Z-adjust customization](Fixed-or-Improved-Logics.md#laser-z-adjust) (by Starkku)
+- [Attached animation draw offset customizations](Fixed-or-Improved-Logics.md#draw-offset-customization) (by Starkku)
+- [Draw offset rules for AttachEffect animations](New-or-Enhanced-Logics.md#attached-effects) by (Starkku)
 
 Vanilla fixes:
 - Fixed sidebar not updating queued unit numbers when adding or removing units when the production is on hold (by CrimRecya)

src/Ext/Anim/Body.cpp

@@ -435,6 +435,7 @@ void AnimExt::ExtData::Serialize(T& Stm)
 		.Process(this->FromWeapon)
 		.Process(this->FromWeaponIdx)
 		.Process(this->FromBurstIdx)
+		.Process(this->AEDrawOffset)
 		;
 }
 

src/Ext/Anim/Body.h

@@ -30,6 +30,7 @@ class AnimExt
 		WeaponTypeClass* FromWeapon;
 		int FromWeaponIdx;
 		int FromBurstIdx;
+		Point2D AEDrawOffset;
 
 		ExtData(AnimClass* OwnerObject) : Extension<AnimClass>(OwnerObject)
 			, DeathUnitFacing { 0 }
@@ -47,6 +48,7 @@ class AnimExt
 			, FromWeapon {}
 			, FromWeaponIdx {}
 			, FromBurstIdx {}
+			, AEDrawOffset { Point2D::Empty }
 		{ }
 
 		void SetInvoker(TechnoClass* pInvoker);

src/Ext/Anim/Hooks.cpp

@@ -270,14 +270,57 @@ DEFINE_HOOK(0x424CF1, AnimClass_Start_DetachedReport, 0x6)
 }
 
 // 0x422CD8 is in an alternate code path only used by anims with ID RING1, unused normally but covering it just because
-DEFINE_HOOK_AGAIN(0x422CD8, AnimClass_DrawIt_XDrawOffset, 0x6)
-DEFINE_HOOK(0x423122, AnimClass_DrawIt_XDrawOffset, 0x6)
+DEFINE_HOOK_AGAIN(0x422CD8, AnimClass_DrawIt_DrawOffset, 0x6)
+DEFINE_HOOK(0x423122, AnimClass_DrawIt_DrawOffset, 0x6)
 {
 	GET(AnimClass* const, pThis, ESI);
 	GET_STACK(Point2D*, pLocation, STACK_OFFSET(0x110, 0x4));
 
-	if (auto const pTypeExt = AnimTypeExt::ExtMap.TryFind(pThis->Type))
-		pLocation->X += pTypeExt->XDrawOffset;
+	auto const pTypeExt = AnimTypeExt::ExtMap.TryFind(pThis->Type);
+	pLocation->X += pTypeExt->XDrawOffset;
+
+	if (pTypeExt->YDrawOffset_ApplyBracketHeight && pThis->OwnerObject && pThis->OwnerObject->AbstractFlags & AbstractFlags::Techno)
+	{
+		// Le magic number.
+		constexpr int SHIELD_HEALTHBAR_OFFSET = -3;
+
+		auto const pTechno = static_cast<TechnoClass*>(pThis->OwnerObject);
+		bool inverse = pTypeExt->YDrawOffset_InvertBracketShift;
+
+		if (auto const pBuilding = abstract_cast<BuildingClass*>(pTechno))
+		{
+			auto const pType = pBuilding->Type;
+
+			if ((pType->Height >= 0 && !inverse) || (pType->Height < 0 && inverse))
+			{
+				auto const pos = TechnoExt::GetBuildingSelectBracketPosition(pBuilding, BuildingSelectBracketPosition::Top);
+				pLocation->Y = pos.Y + pTypeExt->YDrawOffset_BracketAdjust_Buildings.Get(pTypeExt->YDrawOffset_BracketAdjust);
+			}
+		}
+		else
+		{
+			auto const pType = pTechno->GetTechnoType();
+
+			if ((pType->PixelSelectionBracketDelta <= 0 && !inverse) || (pType->PixelSelectionBracketDelta > 0 && inverse))
+			{
+				auto const pos = TechnoExt::GetFootSelectBracketPosition(pTechno, Anchor(HorizontalPosition::Left, VerticalPosition::Top));
+				pLocation->Y = pos.Y + pType->PixelSelectionBracketDelta + pTypeExt->YDrawOffset_BracketAdjust;
+			}
+		}
+
+		if (auto const pShield = TechnoExt::ExtMap.Find(pTechno)->Shield.get())
+		{
+			auto const pShieldType = pShield->GetType();
+
+			if (pShield->IsAvailable() && !pShield->IsBrokenAndNonRespawning() && (pShield->GetHealthRatio() > 0.0 || !pShieldType->Pips_HideIfNoStrength))
+			{
+				if ((pShieldType->BracketDelta <= 0 && !inverse) || (pShieldType->BracketDelta > 0 && inverse))
+					pLocation->Y += pShieldType->BracketDelta + SHIELD_HEALTHBAR_OFFSET;
+			}
+		}
+	}
+
+	*pLocation += AnimExt::ExtMap.Find(pThis)->AEDrawOffset;
 
 	return 0;
 }

src/Ext/AnimType/Body.cpp

@@ -80,6 +80,10 @@ void AnimTypeExt::ExtData::LoadFromINIFile(CCINIClass* pINI)
 
 	this->Palette.LoadFromINI(pINI, pID, "CustomPalette");
 	this->XDrawOffset.Read(exINI, pID, "XDrawOffset");
+	this->YDrawOffset_ApplyBracketHeight.Read(exINI, pID, "YDrawOffset.ApplyBracketHeight");
+	this->YDrawOffset_InvertBracketShift.Read(exINI, pID, "YDrawOffset.InvertBracketShift");
+	this->YDrawOffset_BracketAdjust.Read(exINI, pID, "YDrawOffset.BracketAdjust");
+	this->YDrawOffset_BracketAdjust_Buildings.Read(exINI, pID, "YDrawOffset.BracketAdjust.Buildings");
 	this->HideIfNoOre_Threshold.Read(exINI, pID, "HideIfNoOre.Threshold");
 	this->Layer_UseObjectLayer.Read(exINI, pID, "Layer.UseObjectLayer");
 	this->AttachedAnimPosition.Read(exINI, pID, "AttachedAnimPosition");
@@ -139,6 +143,10 @@ void AnimTypeExt::ExtData::Serialize(T& Stm)
 		.Process(this->Palette)
 		.Process(this->CreateUnitType)
 		.Process(this->XDrawOffset)
+		.Process(this->YDrawOffset_ApplyBracketHeight)
+		.Process(this->YDrawOffset_InvertBracketShift)
+		.Process(this->YDrawOffset_BracketAdjust)
+		.Process(this->YDrawOffset_BracketAdjust_Buildings)
 		.Process(this->HideIfNoOre_Threshold)
 		.Process(this->Layer_UseObjectLayer)
 		.Process(this->AttachedAnimPosition)

src/Ext/AnimType/Body.h

@@ -28,6 +28,10 @@ class AnimTypeExt
 		CustomPalette Palette;
 		std::unique_ptr<CreateUnitTypeClass> CreateUnitType;
 		Valueable<int> XDrawOffset;
+		Valueable<bool> YDrawOffset_ApplyBracketHeight;
+		Valueable<bool> YDrawOffset_InvertBracketShift;
+		Valueable<int> YDrawOffset_BracketAdjust;
+		Nullable<int> YDrawOffset_BracketAdjust_Buildings;
 		Valueable<int> HideIfNoOre_Threshold;
 		Nullable<bool> Layer_UseObjectLayer;
 		Valueable<AttachedAnimPosition> AttachedAnimPosition;
@@ -67,6 +71,8 @@ class AnimTypeExt
 			, Palette { CustomPalette::PaletteMode::Temperate }
 			, CreateUnitType { nullptr }
 			, XDrawOffset { 0 }
+			, YDrawOffset_ApplyBracketHeight { false }
+			, YDrawOffset_InvertBracketShift { false }
 			, HideIfNoOre_Threshold { 0 }
 			, Layer_UseObjectLayer {}
 			, AttachedAnimPosition { AttachedAnimPosition::Default }

src/Ext/Techno/Body.Update.cpp

@@ -1936,7 +1936,10 @@ void TechnoExt::ExtData::UpdateAttachEffects()
 	}
 
 	if (altered)
+	{
 		this->RecalculateStatMultipliers();
+		this->UpdateAEAnimDrawingLogic();
+	}
 
 	if (markForRedraw)
 		pThis->MarkForRedraw();
@@ -2008,7 +2011,10 @@ void TechnoExt::ExtData::UpdateSelfOwnedAttachEffects()
 	const int count = AttachEffectClass::Attach(pThis, pThis->Owner, pThis, pThis, pTypeExt->AttachEffects);
 
 	if (altered && !count)
+	{
 		this->RecalculateStatMultipliers();
+		this->UpdateAEAnimDrawingLogic();
+	}
 }
 
 // Updates CumulativeAnimations AE's on techno.
@@ -2053,6 +2059,15 @@ void TechnoExt::ExtData::UpdateCumulativeAttachEffects(AttachEffectTypeClass* pA
 	}
 }
 
+// Update AttachEffect animation drawing logic.
+void TechnoExt::ExtData::UpdateAEAnimDrawingLogic()
+{
+	for (auto const& attachEffect : this->AttachedEffects)
+	{
+		attachEffect->UpdateConditionalAnimDrawingLogic();
+	}
+}
+
 // Recalculates AttachEffect stat multipliers and other bonuses.
 void TechnoExt::ExtData::RecalculateStatMultipliers()
 {