isolate shield bounce code a bit

why didn't I even look at what the engine does for repulsion, tbh. idk. that's a good question, man.

Author: efrec

luarules/gadgets/unit_custom_weapons_cluster.lua

@@ -256,12 +256,6 @@ local waterFullDeflection = 0.85 -- 1 - vertical response loss
 ---Water is generally incompressible so acts like solid terrain of lower density
 -- when it takes hard impacts or impulses. We take a fast estimate of its added
 -- bulk to the solid terrain below and shift the surface direction toward level.
----@param slope number in radians? in what? is this [0, 1]?
----@param elevation number in elmos, always negative
----@return number percentX
----@return number percentY
----@return number percentZ
----@return number depth
 local function getWaterDeflection(slope, elevation)
 	elevation = max(elevation * waterDepthCoef, waterDepthDeflects)
 	local waterDeflectFraction = min(1, elevation / waterDepthDeflects)
@@ -276,6 +270,50 @@ local function getWaterDeflection(slope, elevation)
 	end
 end
 
+---Shields can overlap with units, terrain, and other shields, so we should avoid both:
+-- (1) exaggerating other responses by adding new responses in the same direction, and
+-- (2) destructively negating other strong responses (> 1) when opposite in direction.
+local function getShieldDeflection(dx, dy, dz, shieldUnits)
+	local ox, oy, oz = dx, dy, dz
+	local responseMax = max(1, diag(ox, oy, oz))
+
+	-- Current code does not detect all shields that should have been "hit" via AOE,
+	-- but multiple hits, while rare, can and do happen, still, in typical gameplay.
+	for _, shieldUnitID in pairs(shieldUnits) do
+		local sx, sy, sz, radius = getShieldPosition(shieldUnitID)
+
+		if sx then
+			sx, sy, sz = dx + (x - sx) / radius, dy + (y - sy) / radius, dz + (z - sz) / radius
+			local response = diag(sx, sy, sz)
+			local limitMin, limitMax = 1, responseMax
+
+			if limitMax > 1 then
+				-- Limits above 1 are in the direction of the original response,
+				-- with the limits at 90 degrees from that direction equal to 1,
+				-- and the limits facing > 90 degrees away from it less than 1.
+				local codirection = (ox * sx + oy * sy + oz * sz) / limitMax
+				if codirection < 0 then
+					limitMin = min(-codirection, limitMin)
+					limitMax = 1
+					codirection = codirection + 1
+				end
+				limitMax = clamp(codirection, limitMin, limitMax)
+			end
+
+			-- Shields can overlap units, terrain, and other shields, so
+			-- they need to avoid exaggerating other existing responses.
+			if response > limitMax and response > 0 then
+				local ratio = limitMax / response
+				sx, sy, sz = sx * ratio, sy * ratio, sz * ratio
+			end
+
+			dx, dy, dz = sx, sy, sz
+		end
+	end
+
+	return dx, dy, dz
+end
+
 ---Deflection from solid terrain and unit collider surfaces plus water by depth.
 local function getSurfaceDeflection(x, y, z, shieldUnits)
 	local elevation = spGetGroundHeight(x, z)
@@ -340,35 +378,7 @@ local function getSurfaceDeflection(x, y, z, shieldUnits)
 
 	-- Additional deflection from shields, which are solid-terrain-like.
 	if shieldUnits then
-		local ox, oy, oz = dx, dy, dz
-		local responseMax = max(1, diag(ox, oy, oz)) -- limit responses when > 1
-
-		-- A hit to multiple shields is an exceptional case since they don't seem to be damaged by AOE.
-		for _, shieldUnitID in pairs(shieldUnits) do
-			unitX, unitY, unitZ, radius = getShieldPosition(shieldUnitID)
-			if unitX then
-				local rx, ry, rz = dx + (x - unitX) / radius, dy + (y - unitY) / radius, dz + (z - unitZ) / radius
-				local response = diag(rx, ry, rz)
-
-				local limitMin, limitMax = 1, responseMax
-				if limitMax > 1 then
-					-- Shields can overlap units so we want to avoid an exaggerated response.
-					local codirection = (ox * rx + oy * ry + oz * rz) / limitMax
-					if codirection < 0 then
-						limitMin = min(-codirection, limitMin) -- don't produce over-corrections
-						codirection = codirection + 1 -- directions were opposite of each other
-						limitMax = 1 -- don't produce under-corrections
-					end
-					limitMax = clamp(codirection, limitMin, limitMax)
-				end
-				if response > limitMax and response > 0 then
-					local ratio = limitMax / response
-					rx, ry, rz = rx * ratio, ry * ratio, rz * ratio
-				end
-
-				dx, dy, dz = rx, ry, rz
-			end
-		end
+		dx, dy, dz = getShieldDeflection(dx, dy, dz, shieldUnits)
 	end
 
 	return dx, dy, dz