Fix annotation warnings in weapon.lua (#6575)

changelog/snippets/other.6575.md

@@ -0,0 +1 @@
+- (#6575) Add remaining annotations for the base weapon class file.

engine/Core/Blueprints/WeaponBlueprint.lua

@@ -219,7 +219,7 @@
 ---@field NukeInnerRingRadius? number
 --- How many damage ticks the inner damage ring of the nuke will be applied over to get from the
 --- epicenter to the inner ring radius. The ring will be broken up into this many disks.
----@field NukeInnerRingTicks? number
+---@field NukeInnerRingTicks? integer
 --- The total time in seconds it takes the inner damage ring to apply its damage from the epicenter
 --- of the nuke to its inner ring radius. If `0` or `1`, this behaves as a damage area.
 ---@field NukeInnerRingTotalTime? number
@@ -230,7 +230,7 @@
 ---@field NukeOuterRingRadius? number
 --- How many damage ticks the outer damage ring of the nuke will be applied over to get from the
 --- epicenter to the outer ring radius. The ring will be broken up into this many disks.
----@field NukeOuterRingTicks? number
+---@field NukeOuterRingTicks? integer
 --- The total time in seconds it takes the outer damage ring to apply its damage from the epicenter
 --- of the nuke to its outer ring radius. If `0` or `1`, this behaves as a damage area.
 ---@field NukeOuterRingTotalTime? number
@@ -331,7 +331,7 @@
 ---@field TurretBoneYaw? Bone
 --- If two manipulators are needed for this weapon. Used for bots with arms.
 ---@field TurretDualManipulators? boolean
---- if this weapon has a turret
+--- if this weapon has a turret. Defaults to false
 ---@field Turreted boolean
 --- the center angle for determining pitch, based off the rest pose of the model
 ---@field TurretPitch number

lua/sim/Projectile.lua

@@ -89,10 +89,10 @@ local VectorCached = Vector(0, 0, 0)
 
 ---@class Projectile : moho.projectile_methods, InternalObject, DebugProjectileComponent
 ---@field Blueprint ProjectileBlueprint
----@field Army number
+---@field Army Army
 ---@field Trash TrashBag
 ---@field Launcher Unit
----@field OriginalTarget? Unit
+---@field OriginalTarget? Unit | Blip
 ---@field DamageData WeaponDamageTable
 ---@field MyDepthCharge? DepthCharge    # If weapon blueprint has a (valid) `DepthCharge` field
 ---@field MyFlare? Flare            # If weapon blueprint has a (valid) `Flare` field

lua/sim/weapon.lua

@@ -11,6 +11,7 @@
 local Entity = import("/lua/sim/entity.lua").Entity
 local NukeDamage = import("/lua/sim/nukedamage.lua").NukeAOE
 local ParseEntityCategoryProperly = import("/lua/sim/categoryutils.lua").ParseEntityCategoryProperly
+---@type false | EntityCategory[]
 local cachedPriorities = false
 local RecycledPriTable = {}
 
@@ -34,6 +35,7 @@ local DebugWeaponComponent = import("/lua/sim/weapons/components/DebugWeaponComp
 ---@field Buffs BlueprintBuff[]         # Active buffs for the weapon
 ---@field __index WeaponDamageTable
 
+---@return EntityCategory[]
 local function ParsePriorities()
     local idlist = EntityCategoryGetUnitList(categories.ALLUNITS)
     local finalPriorities = {}
@@ -72,6 +74,7 @@ local WeaponMethods = moho.weapon_methods
 ---@field AimLeft? moho.AimManipulator
 ---@field AimRight? moho.AimManipulator
 ---@field Army Army
+---@field AmbientSounds table<SoundBlueprint, Entity>
 ---@field Blueprint WeaponBlueprint
 ---@field Brain AIBrain
 ---@field CollideFriendly boolean
@@ -80,6 +83,7 @@ local WeaponMethods = moho.weapon_methods
 ---@field DamageRadiusMod number
 ---@field damageTableCache WeaponDamageTable | false # Set to false when the weapon's damage is modified
 ---@field DisabledBuffs table
+---@field DisabledFiringBones Bone[] # Bones that `Unit.Animator` cannot move when this weapon has a target
 ---@field EnergyRequired? number
 ---@field EnergyDrainPerSecond? number
 ---@field Label string
@@ -88,6 +92,7 @@ local WeaponMethods = moho.weapon_methods
 ---@field unit Unit
 ---@field MaxRadius? number
 ---@field MinRadius? number
+---@field onTransport boolean # True if the parent unit has been loaded on to a transport unit.
 Weapon = ClassWeapon(WeaponMethods, DebugWeaponComponent) {
 
     -- stored here for mods compatibility, overridden in the inner table when written to
@@ -173,6 +178,7 @@ Weapon = ClassWeapon(WeaponMethods, DebugWeaponComponent) {
         end
 
         local unit = self.unit
+        ---@diagnostic disable-next-line: param-type-mismatch
         if not (unit:ValidateBone(yawBone) and unit:ValidateBone(pitchBone) and unit:ValidateBone(muzzleBone)) then
             error('*ERROR: Bone aborting turret setup due to bone issues.', 2)
             return
@@ -377,7 +383,8 @@ Weapon = ClassWeapon(WeaponMethods, DebugWeaponComponent) {
 
     ---@param self Weapon
     OnGotTarget = function(self)
-        local animator = self.unit.Animator
+        -- a few non-walker units may use `Animator` as well
+        local animator = self.unit--[[@as WalkingLandUnit]].Animator
         if self.DisabledFiringBones and animator then
             for _, value in self.DisabledFiringBones do
                 animator:SetBoneEnabled(value, false)
@@ -387,7 +394,8 @@ Weapon = ClassWeapon(WeaponMethods, DebugWeaponComponent) {
 
     ---@param self Weapon
     OnLostTarget = function(self)
-        local animator = self.unit.Animator
+        -- a few non-walker units may use `Animator` as well
+        local animator = self.unit--[[@as WalkingLandUnit]].Animator
         if self.DisabledFiringBones and animator then
             for _, value in self.DisabledFiringBones do
                 animator:SetBoneEnabled(value, true)
@@ -413,15 +421,15 @@ Weapon = ClassWeapon(WeaponMethods, DebugWeaponComponent) {
     end,
 
     ---@param self Weapon
-    ---@param sound SoundBlueprint
+    ---@param sound SoundBlueprint | string # The string is the key for the audio in the weapon blueprint
     PlayWeaponSound = function(self, sound)
         local weaponSound = self.Blueprint.Audio[sound]
         if not weaponSound then return end
         self:PlaySound(weaponSound)
     end,
 
     ---@param self Weapon
-    ---@param sound SoundBlueprint
+    ---@param sound SoundBlueprint | string # The string is the key for the audio in the weapon blueprint
     PlayWeaponAmbientSound = function(self, sound)
         local audio = self.Blueprint.Audio[sound]
         if not audio then return end
@@ -432,6 +440,7 @@ Weapon = ClassWeapon(WeaponMethods, DebugWeaponComponent) {
         end
         local ambientSound = ambientSounds[sound]
         if not ambientSound then
+            ---@type Entity
             ambientSound = Entity {}
             ambientSounds[sound] = ambientSound
             self.Trash:Add(ambientSound)
@@ -441,7 +450,7 @@ Weapon = ClassWeapon(WeaponMethods, DebugWeaponComponent) {
     end,
 
     ---@param self Weapon
-    ---@param sound SoundBlueprint
+    ---@param sound SoundBlueprint | string # The string is the key for the audio in the weapon blueprint
     StopWeaponAmbientSound = function(self, sound)
         local ambientSounds = self.AmbientSounds
         if not ambientSounds then return end
@@ -562,7 +571,7 @@ Weapon = ClassWeapon(WeaponMethods, DebugWeaponComponent) {
     end,
 
     ---@param self Weapon
-    ---@param priorities number
+    ---@param priorities? EntityCategory[] | UnparsedCategory[] | false
     SetWeaponPriorities = function(self, priorities)
         if priorities then
             if type(priorities[1]) == 'string' then

lua/sim/weapons/DefaultProjectileWeapon.lua

@@ -62,19 +62,19 @@ DefaultProjectileWeapon = ClassWeapon(Weapon) {
         -- Make certain the weapon has essential aspects defined
         if not rackBones then
             local strg = '*ERROR: No RackBones table specified, aborting weapon setup.  Weapon: ' ..
-                bp.DisplayName .. ' on Unit: ' .. self.unit:GetUnitId()
+                (bp.Label or bp.DisplayName or 'Unlabelled') .. ' on Unit: ' .. self.unit:GetUnitId()
             error(strg, 2)
             return
         end
         if not muzzleSalvoSize then
             local strg = '*ERROR: No MuzzleSalvoSize specified, aborting weapon setup.  Weapon: ' ..
-                bp.DisplayName .. ' on Unit: ' .. self.unit:GetUnitId()
+                (bp.Label or bp.DisplayName or 'Unlabelled') .. ' on Unit: ' .. self.unit:GetUnitId()
             error(strg, 2)
             return
         end
         if not muzzleSalvoDelay then
             local strg = '*ERROR: No MuzzleSalvoDelay specified, aborting weapon setup.  Weapon: ' ..
-                bp.DisplayName .. ' on Unit: ' .. self.unit:GetUnitId()
+                (bp.Label or bp.DisplayName or 'Unlabelled') .. ' on Unit: ' .. self.unit:GetUnitId()
             error(strg, 2)
             return
         end