Annotate fields related to bombs (#6181)

Author: lL1l1

changelog/snippets/other.6181.md

@@ -0,0 +1 @@
+- (#6181) Annotate fields and functions related to bomb projectiles.

engine/Core/Blueprints/ProjectileBlueprint.lua

@@ -66,7 +66,7 @@
 ---@field LeadTarget boolean
 --- Whether projectiles should try to stay underwater. Applies only to tracking projectiles.
 ---@field StayUnderwater boolean
---- if the projectile is initially affected by gravity
+--- if the projectile is initially affected by gravity (-4.9 ogrids/second/second)
 ---@field UseGravity boolean
 --- projectile will detonate when going above this height above ground
 ---@field DetonateAboveHeight number
@@ -133,7 +133,8 @@
 ---@field MaxZigZag number
 --- frequency of zig-zag directional changes, in seconds
 ---@field ZigZagFrequency number
---- realistic free fall ordinance type weapon
+--- When true and weapon muzzle velocity is 0, the projectile's horizontal velocity is set in the direction of the target with the speed of the weapon firing the projectile.
+--- Used for realistic free fall ordinance type weapons like bombs
 ---@field RealisticOrdinance boolean
 --- bombs that always drop stright down
 ---@field StraightDownOrdinance boolean

engine/Core/Blueprints/WeaponBlueprint.lua

@@ -51,7 +51,7 @@
 ---@field BeamLifetime number
 --- if the weapon will only fire when underwater
 ---@field BelowWaterFireOnly? boolean
---- threshold to release point before releasing ordnance
+--- Distance from bomb firing solution's position to the target's position within which the weapon will fire 
 ---@field BombDropThreshold? number
 --- information about the bonuses added to the weapon when it reaches a specific veterancy level
 ---@field Buffs BlueprintBuff[]

engine/Sim/Projectile.lua

@@ -90,7 +90,7 @@ end
 function Projectile:SetAcceleration(accel)
 end
 
---- Define the ballistic acceleration value, increases velocity in the current direction.
+--- Set the vertical (gravitational) acceleration of the projectile. Default is -4.9, which is expected by the engine's weapon targeting and firing
 ---@param accel number
 function Projectile:SetBallisticAcceleration(accel)
 end

lua/sim/weapons/DefaultProjectileWeapon.lua

@@ -187,13 +187,14 @@ DefaultProjectileWeapon = ClassWeapon(Weapon) {
         proj:SetBallisticAcceleration(-self:CalculateBallisticAcceleration(proj))
     end,
 
+    --- Returns the positive downwards acceleration needed for a projectile to hit its target when travelling at the same speed as the unit launching it (for bombs)
     ---@param self DefaultProjectileWeapon
     ---@param projectile Projectile
     ---@return number
     CalculateBallisticAcceleration = function(self, projectile)
         local launcher = projectile:GetLauncher()
         if not launcher then -- fail-fast
-            return 4.75
+            return 4.9 -- Return the default gravity value if some calculations fail
         end
 
         local UnitGetVelocity = UnitGetVelocity
@@ -225,15 +226,15 @@ DefaultProjectileWeapon = ClassWeapon(Weapon) {
             if self.Blueprint.MuzzleSalvoSize <= 1 then
                 -- do the calculation but skip any cache or salvo logic
                 if not targetPos then
-                    return 4.75
+                    return 4.9
                 end
                 if target and not target.IsProp then
                     targetVelX, _, targetVelZ = UnitGetVelocity(target)
                 end
                 local targetPosX, targetPosZ = targetPos[1], targetPos[3]
                 local distVel = VDist2(projVelX, projVelZ, targetVelX, targetVelZ)
                 if distVel == 0 then
-                    return 4.75
+                    return 4.9
                 end
                 local distPos = VDist2(projPosX, projPosZ, targetPosX, targetPosZ)
                 do
@@ -243,14 +244,14 @@ DefaultProjectileWeapon = ClassWeapon(Weapon) {
                     end
                 end
                 if distPos == 0 then
-                    return 4.75
+                    return 4.9
                 end
                 local time = distPos / distVel
                 projPosY = projPosY - GetSurfaceHeight(targetPosX + time * targetVelX, targetPosZ + time * targetVelZ)
                 return 200 * projPosY / (time * time)
             else -- otherwise, calculate & cache a couple things the first time only
                 data = {
-                    lastAccel = 4.75,
+                    lastAccel = 4.9,
                     targetPos = targetPos,
                 }
                 if target then
@@ -283,19 +284,19 @@ DefaultProjectileWeapon = ClassWeapon(Weapon) {
             local GetSurfaceHeight = GetSurfaceHeight
             local MathSqrt = math.sqrt
             local spread = self.AdjustedSalvoDelay * (self.SalvoSpreadStart + self.CurrentSalvoNumber)
-            -- nominal acceleration is 4.75; however, bomb clusters adjust the time it takes to land
+            -- default gravitational acceleration is 4.9; however, bomb clusters adjust the time it takes to land
             -- so we convert the acceleration to time to add the spread and convert back:
             -- h = unitY - surfaceY         =>  h2 = 0.5 * (unitY - surfaceHeight(unitX, unitZ))
-            -- t = sqrt(2 h / a) + spread   =>  t = sqrt(4 / 4.75 * h2) + spread
+            -- t = sqrt(2 h / a) + spread   =>  t = sqrt(4 / 4.9 * h2) + spread
             -- a = 0.5 h / t^2              =>  a = h2 / t^2
             local halfHeight = 0.5 * (projPosY - GetSurfaceHeight(projPosX, projPosZ))
-            if halfHeight < 0.01 then return 4.75 end
-            local time = MathSqrt(0.842105263158 * halfHeight) + spread
+            if halfHeight < 0.01 then return 4.9 end
+            local time = MathSqrt(0.816326530612 * halfHeight) + spread
 
             -- now that we know roughly when we'll land, we can find a better guess for where
             -- we'll land, and thus guess the true falling height better as well
             halfHeight = 0.5 * (projPosY - GetSurfaceHeight(projPosX + time * projVelX, projPosX + time * projVelX))
-            time = MathSqrt(0.842105263158 * halfHeight) + spread
+            time = MathSqrt(0.816326530612 * halfHeight) + spread
 
             local acc = halfHeight / (time * time)
             data.lastAccel = acc
@@ -306,8 +307,8 @@ DefaultProjectileWeapon = ClassWeapon(Weapon) {
         -- velocity will eventually need to multiplied by 10 due to being per tick instead of per second
         local distVel = VDist2(projVelX, projVelZ, targetVelX, targetVelZ)
         if distVel == 0 then
-            data.lastAccel = 4.75
-            return 4.75
+            data.lastAccel = 4.9
+            return 4.9
         end
         local targetPosX, targetPosZ = targetPos[1], targetPos[3]
 
@@ -324,8 +325,8 @@ DefaultProjectileWeapon = ClassWeapon(Weapon) {
         local time = distPos / distVel
         local adjustedTime = time + self.AdjustedSalvoDelay * (self.SalvoSpreadStart + self.CurrentSalvoNumber)
         if adjustedTime == 0 then
-            data.lastAccel = 4.75
-            return 4.75
+            data.lastAccel = 4.9
+            return 4.9
         end
 
         -- If we have a target, targetPos may have updated now.