platoon.lua annotation and warning fixes [auxiliary files]

engine/Core.lua

@@ -14,6 +14,9 @@
 ---@field [1] number    # x
 ---@field [2] number    # y (up)
 ---@field [3] number    # z
+---@field x number      # east/west
+---@field y number      # up/down
+---@field z number      # north/south
 
 ---@class Vector2
 ---@field [1] number    # x

engine/Sim/CAiBrain.lua

@@ -138,7 +138,7 @@ end
 --- points in the template are used.
 ---
 ---@param type          string
----@param structureName filename # blueprint file
+---@param structureName FileName # blueprint file
 ---@param buildingTypes BuildingTemplate[]
 ---@param relative      boolean
 ---@param builder       Unit
@@ -258,7 +258,7 @@ function CAiBrain:GetBlueprintStat(statName, category)
 end
 
 --- Return this brain's current enemy.
--- @return Number, target's army number.
+---@return number -- target army's number
 function CAiBrain:GetCurrentEnemy()
 end
 
@@ -394,7 +394,7 @@ end
 ---@param position Vector
 ---@param radius number in game units
 ---@param restriction boolean
----@param threatType BrainThreatType
+---@param threatType? BrainThreatType
 ---@param armyIndex? number defaults to this brain's index
 ---@return number
 function CAiBrain:GetThreatAtPosition(position, radius, restriction, threatType, armyIndex)

engine/Sim/CPlatoon.lua

@@ -12,15 +12,15 @@ local CPlatoon = {}
 --- Orders platoon to attack target unit.
 -- If squad is specified, attacks only with the squad.
 ---@param target Unit Unit to attack.
----@param squad PlatoonSquadType
+---@param squad? PlatoonSquadType
 ---@return PlatoonCommand
 function CPlatoon:AttackTarget(target, squad)
 end
 
 --- Orders platoon to attack mote to target position..
 -- If squad is specified, attack moves only with the squad.
 ---@param position Vector Table with position {x, y, z}.
----@param squad PlatoonSquadType?
+---@param squad? PlatoonSquadType
 ---@return PlatoonCommand
 function CPlatoon:AggressiveMoveToLocation(position, squad)
 end
@@ -252,7 +252,7 @@ end
 --- Orders platoon to patrol at target position.
 -- If squad is specified, patrols only with the squad.
 ---@param position Vector Table with position {x, y, z}.
----@param squad PlatoonSquadType
+---@param squad? PlatoonSquadType
 ---@return PlatoonCommand
 function CPlatoon:Patrol(position, squad)
 end

engine/Sim/Unit.lua

@@ -604,7 +604,7 @@ function Unit:SetRegenRate(rate)
 end
 
 --- sets the script bit
----@param bit number
+---@param bit number|string
 ---@param state boolean
 function Unit:SetScriptBit(bit, state)
 end

lua/AI/AIBehaviors.lua

@@ -1455,10 +1455,10 @@ end
 
 ---@param attackingUnit Unit
 ---@param targetUnit Unit
----@return boolean
+---@return Unit? targetShield
 function GetClosestShieldProtectingTargetSorian(attackingUnit, targetUnit)
     if not targetUnit or not attackingUnit then
-        return false
+        return
     end
     local blockingList = {}
 
@@ -1479,7 +1479,7 @@ function GetClosestShieldProtectingTargetSorian(attackingUnit, targetUnit)
     end
 
     -- Return the closest blocking shield
-    local closest = false
+    local closest
     local closestDistSq = 999999
     for _, shield in blockingList do
         local shieldPos = shield:GetPosition()

lua/AI/OpAI/BaseManager.lua

@@ -10,9 +10,11 @@
 
 ---@class MarkerChain: string                   # Name reference to a marker chain as defined in the map
 ---@class Area: string                          # Name reference to a area as defined in the map
----@class Marker: string                        # Name reference to a marker as defined in the map
 ---@class UnitGroup: string                     # Name reference to a unit group as defined in the map
 
+---@class Marker: string                        # Name reference to a marker as defined in the map
+---@field Position Vector                       # A { x, y, z } array-based table
+
 -- types commonly used in repository
 
 ---@class FunctionName: string

lua/AI/aibuildstructures.lua

@@ -352,8 +352,8 @@ function AIBuildBaseTemplateOrdered(aiBrain, builder, buildingType , closeToBuil
     return -- unsuccessful build
 end
 
----@param baseTemplate any
----@param location Vector
+---@param baseTemplate? any
+---@param location? Vector
 ---@return table
 function AIBuildBaseTemplateFromLocation(baseTemplate, location)
     local baseT = {}

lua/AI/sorianutilities.lua

@@ -414,7 +414,7 @@ end
 --- Finds a custom engineer built unit to replace a default one.
 ---@param aiBrain AIBrain
 ---@param building Unit
----@param faction string
+---@param faction? string
 ---@param buildingTmpl string
 ---@return boolean|table
 function GetTemplateReplacement(aiBrain, building, faction, buildingTmpl)
@@ -449,7 +449,7 @@ function GetTemplateReplacement(aiBrain, building, faction, buildingTmpl)
 end
 
 ---@param engineer Unit
----@return string|boolean
+---@return string?
 function GetEngineerFaction(engineer)
     if EntityCategoryContains(categories.UEF, engineer) then
         return 'UEF'
@@ -462,7 +462,7 @@ function GetEngineerFaction(engineer)
     elseif EntityCategoryContains(categories.NOMADS, engineer) then
         return 'Nomads'
     else
-        return false
+        return
     end
 end
 

lua/aibrain.lua

@@ -24,6 +24,10 @@ local CoroutineYield = coroutine.yield
 ---@field OnceOnly boolean
 ---@field TargetAIBrain AIBrain
 
+---@class ScoutLocation
+---@field Position Vector
+---@field TaggedBy Unit
+
 ---@class PlatoonTable
 ---@alias AIResult "defeat" | "draw" | "victor"
 ---@alias HqTech "TECH2" | "TECH3"
@@ -547,6 +551,7 @@ local CategoriesDummyUnit = categories.DUMMYUNIT
 ---@field UnitBuiltTriggerList table
 ---@field PingCallbackList { CallbackFunction: fun(pingData: any), PingType: string }[]
 ---@field BrainType 'Human' | 'AI'
+---@field CustomUnits { [string]: EntityId[] }
 AIBrain = Class(AIBrainHQComponent, AIBrainStatisticsComponent, AIBrainJammerComponent, AIBrainEnergyComponent,
     moho.aibrain_methods) {
 

lua/aibrains/base-ai.lua

@@ -59,10 +59,13 @@ local StandardBrain = import("/lua/aibrain.lua").AIBrain
 ---@field EnergyDepleted boolean
 ---@field EconomyTicksMonitor number
 ---@field HasPlatoonList boolean
+---@field IMAPConfig table
 ---@field IntelData? table<string, number>
 ---@field IntelTriggerList table
+---@field InterestList table
 ---@field LayerPref "LAND" | "AIR"
 ---@field Name string
+---@field NumOpponents number
 ---@field Radars table<string, Unit[]>
 ---@field Result? AIResult
 ---@field Sorian boolean
@@ -308,10 +311,10 @@ AIBrain = Class(StandardBrain) {
 
     ---@param self BaseAIBrain
     ---@param loc Vector
-    ---@return Vector | false
+    ---@return Vector?
     PBMGetLocationCoords = function(self, loc)
         if not loc then
-            return false
+            return
         end
         if self.HasPlatoonList then
             for _, v in self.PBM.Locations do
@@ -326,7 +329,7 @@ AIBrain = Class(StandardBrain) {
         elseif self.BuilderManagers[loc] then
             return self.BuilderManagers[loc].FactoryManager:GetLocationCoords()
         end
-        return false
+        return
     end,
 
     ---@param self BaseAIBrain
@@ -792,10 +795,10 @@ AIBrain = Class(StandardBrain) {
     ---@param self BaseAIBrain
     ---@param position Vector
     ---@param radius number
-    ---@param threshold number
-    ---@return boolean|table
+    ---@param threshold? number
+    ---@return Vector?
     BaseMonitorDistressLocation = function(self, position, radius, threshold)
-        local returnPos = false
+        local returnPos
         local highThreat = false
         local distance
         if self.BaseMonitor.CDRDistress
@@ -1313,7 +1316,7 @@ AIBrain = Class(StandardBrain) {
     ---## Function: GetUntaggedMustScoutArea
     --- Gets an area that has been flagged with the AddScoutArea function that does not have a unit heading to scout it already.
     ---@param self BaseAIBrain
-    ---@return Vector location
+    ---@return ScoutLocation location
     ---@return number index
     GetUntaggedMustScoutArea = function(self)
         -- If any locations have been specifically tagged for scouting

lua/aibrains/campaign-ai.lua

@@ -816,11 +816,11 @@ AIBrain = Class(StandardBrain) {
     end,
 
     ---@param self CampaignAIBrain
-    ---@param loc Vector
-    ---@return Vector | false
+    ---@param loc string
+    ---@return Vector?
     PBMGetLocationCoords = function(self, loc)
         if not loc then
-            return false
+            return
         end
         if self.HasPlatoonList then
             for _, v in self.PBM.Locations do
@@ -835,7 +835,6 @@ AIBrain = Class(StandardBrain) {
         elseif self.BuilderManagers[loc] then
             return self.BuilderManagers[loc].FactoryManager:GetLocationCoords()
         end
-        return false
     end,
 
     ---@param self CampaignAIBrain

lua/shared/NavGenerator.lua

@@ -139,7 +139,15 @@ end
 --- | 'Air' 
 --- | 'Naval'
 
----@type table<AIThreatFunctionNames, fun(aiBrain: AIBrain, position: Vector, radius: number) : number>
+---@class ThreatFunctions: table
+---@field Land function
+---@field Air function
+---@field Naval function
+---@field AntiSurface function
+---@field AntiSub function
+---@field AntiAir function
+---@field MobileAntiSurface function
+---@field StructureAntiSurface function
 ThreatFunctions = {
     ---@param aibrain AIBrain
     ---@param position Vector

lua/sim/Builder.lua

@@ -438,7 +438,12 @@ end
 --   }
 --}
 
----@class EngineerBuilder : PlatoonBuilder
+---@class EngineerBuilder : PlatoonBuilder, Unit
+---@field ProcessBuild? thread
+---@field ProcessBuildDone boolean
+---@field EngineerBuildQueue table
+---@field AssistSet boolean
+---@field AssistPlatoon Platoon
 EngineerBuilder = Class(PlatoonBuilder) {
     ---@param self EngineerBuilder
     ---@param brain AIBrain

lua/sim/Unit.lua

@@ -119,6 +119,7 @@ local cUnit = moho.unit_methods
 local cUnitGetBuildRate = cUnit.GetBuildRate
 
 ---@class Unit : moho.unit_methods, InternalObject, IntelComponent, VeterancyComponent, AIUnitProperties, UnitBuffFields
+---@field CDRHome? LocationType
 ---@field AIManagerIdentifier? string
 ---@field Repairers table<EntityId, Unit>
 ---@field Brain AIBrain
@@ -149,6 +150,7 @@ local cUnitGetBuildRate = cUnit.GetBuildRate
 ---@field SiloProjectile? ProjectileBlueprint
 ---@field ReclaimTimeMultiplier? number
 ---@field CaptureTimeMultiplier? number
+---@field PlatoonHandle? Platoon
 Unit = ClassUnit(moho.unit_methods, IntelComponent, VeterancyComponent) {
 
     IsUnit = true,

lua/system/utils.lua

@@ -74,13 +74,15 @@ function table.getsize(t)
 end
 
 --- table.copy(t) returns a shallow copy of t.
+---@overload fun(t: Vector): Vector
 function table.copy(t)
-    if not t then return end -- prevents looping over nil table
-    local r = {}
-    for k,v in t do
-        r[k] = v
+    if t then -- prevents looping over nil table
+        local r = {}
+        for k,v in t do
+            r[k] = v
+        end
+        return r
     end
-    return r
 end
 
 --- table.find(t,val) returns the key for val if it is in t table.