Annotate the damage data passed from weapons to projectiles (#6458)

This is the table passed from weapons to projectiles so that the
projectiles know their damage-dealing behavior.

changelog/snippets/sections/other.6458.md

@@ -0,0 +1 @@
+- (#6458) Annotate the damage data table passed from weapons to projectiles.

lua/sim/CollisionBeam.lua

@@ -19,6 +19,7 @@ local GetTerrainType = GetTerrainType
 local DefaultTerrainType = GetTerrainType(-1, -1)
 
 ---@class CollisionBeam : moho.CollisionBeamEntity
+---@field DamageTable WeaponDamageTable
 ---@field Trash TrashBag
 CollisionBeam = Class(moho.CollisionBeamEntity) {
 
@@ -358,9 +359,11 @@ CollisionBeam = Class(moho.CollisionBeamEntity) {
         return self.CollideFriendly
     end,
 
+    --- Creates a new `WeaponDamageTable` in `self.DamageTable` using the weapon blueprint
     ---@param self CollisionBeam
     SetDamageTable = function(self)
         local weaponBlueprint = self.Weapon:GetBlueprint()
+        ---@type WeaponDamageTable
         self.DamageTable = {}
         self.DamageTable.DamageRadius = weaponBlueprint.DamageRadius
         self.DamageTable.DamageAmount = weaponBlueprint.Damage

lua/sim/Projectile.lua

@@ -93,7 +93,7 @@ local VectorCached = Vector(0, 0, 0)
 ---@field Trash TrashBag
 ---@field Launcher Unit
 ---@field OriginalTarget? Unit
----@field DamageData table
+---@field DamageData WeaponDamageTable
 ---@field CreatedByWeapon Weapon
 ---@field IsRedirected? boolean
 ---@field InnerRing? NukeAOE
@@ -605,7 +605,7 @@ Projectile = ClassProjectile(ProjectileMethods, DebugProjectileComponent) {
 
     --- Called by Lua to pass the damage data as a metatable
     ---@param self Projectile
-    ---@param data table
+    ---@param data WeaponDamageTable
     PassMetaDamage = function(self, data)
         self.DamageData = {}
         setmetatable(self.DamageData, data)
@@ -619,7 +619,7 @@ Projectile = ClassProjectile(ProjectileMethods, DebugProjectileComponent) {
     -- @param cachedPosition A cached position that is passed to prevent table allocations, can not be used in fork threads and / or after a yield statement
     ---@param self Projectile
     ---@param instigator Unit
-    ---@param DamageData table
+    ---@param DamageData WeaponDamageTable # passed by the weapon
     ---@param targetEntity Unit | Prop | nil
     ---@param cachedPosition Vector
     DoDamage = function(self, instigator, DamageData, targetEntity, cachedPosition)
@@ -1033,7 +1033,7 @@ Projectile = ClassProjectile(ProjectileMethods, DebugProjectileComponent) {
 
     ---@deprecated
     ---@param self Projectile
-    ---@param DamageData table
+    ---@param DamageData WeaponDamageTable
     PassDamageData = function(self, DamageData)
         self.DamageData = {}
         self.DamageData.DamageRadius = DamageData.DamageRadius
@@ -1046,7 +1046,7 @@ Projectile = ClassProjectile(ProjectileMethods, DebugProjectileComponent) {
         self.DamageData.Buffs = DamageData.Buffs
         self.DamageData.ArtilleryShieldBlocks = DamageData.ArtilleryShieldBlocks
         self.DamageData.InitialDamageAmount = DamageData.InitialDamageAmount
-        self.CollideFriendly = self.DamageData.CollideFriendly
+        self.CollideFriendly = DamageData.CollideFriendly
     end,
 
     ---root of all performance evil

lua/sim/weapon.lua

@@ -16,6 +16,24 @@ local RecycledPriTable = {}
 
 local DebugWeaponComponent = import("/lua/sim/weapons/components/DebugWeaponComponent.lua").DebugWeaponComponent
 
+--- Table of damage information passed from the weapon to the projectile
+--- Can be assigned as a meta table to the projectile's damage table to reduce memory usage for unchanged values
+---@class WeaponDamageTable
+---@field DamageToShields number        # weaponBlueprint.DamageToShields 
+---@field InitialDamageAmount number    # weaponBlueprint.InitialDamage or 0
+---@field DamageRadius number           # weaponBlueprint.DamageRadius + Weapon.DamageRadiusMod
+---@field DamageAmount number           # weaponBlueprint.Damage + Weapon.DamageMod
+---@field DamageType DamageType         # weaponBlueprint.DamageType
+---@field DamageFriendly boolean        # weaponBlueprint.DamageFriendly or true
+---@field CollideFriendly boolean       # weaponBlueprint.CollideFriendly or false
+---@field DoTTime number                # weaponBlueprint.DoTTime
+---@field DoTPulses number              # weaponBlueprint.DoTPulses
+---@field MetaImpactAmount any          # weaponBlueprint.MetaImpactAmount
+---@field MetaImpactRadius any          # weaponBlueprint.MetaImpactRadius
+---@field ArtilleryShieldBlocks boolean # weaponBlueprint.ArtilleryShieldBlocks
+---@field Buffs BlueprintBuff[]         # Active buffs for the weapon
+---@field __index WeaponDamageTable
+
 local function ParsePriorities()
     local idlist = EntityCategoryGetUnitList(categories.ALLUNITS)
     local finalPriorities = {}
@@ -59,6 +77,7 @@ local WeaponMethods = moho.weapon_methods
 ---@field CollideFriendly boolean
 ---@field DamageMod number
 ---@field DamageRadiusMod number
+---@field damageTableCache WeaponDamageTable | false # Set to false when the weapon's damage is modified
 ---@field DisabledBuffs table
 ---@field EnergyRequired? number
 ---@field EnergyDrainPerSecond? number
@@ -441,8 +460,9 @@ Weapon = ClassWeapon(WeaponMethods, DebugWeaponComponent) {
     ---@param self Weapon
     GetDamageTableInternal = function(self)
         local weaponBlueprint = self.Blueprint
+        ---@type WeaponDamageTable
         local damageTable = {}
-        
+
         damageTable.DamageToShields = weaponBlueprint.DamageToShields
         damageTable.InitialDamageAmount = weaponBlueprint.InitialDamage or 0
         damageTable.DamageRadius = weaponBlueprint.DamageRadius + self.DamageRadiusMod
@@ -476,12 +496,12 @@ Weapon = ClassWeapon(WeaponMethods, DebugWeaponComponent) {
 
     damageTableCache = false,
     ---@param self Weapon
-    ---@return table | boolean
+    ---@return WeaponDamageTable
     GetDamageTable = function(self)
         if not self.damageTableCache then
             self.damageTableCache = self:GetDamageTableInternal()
         end
-        return self.damageTableCache
+        return self.damageTableCache --[[@as WeaponDamageTable]]
     end,
 
     ---@param self Weapon