Refactor and annotate more of BaseManager

changelog/snippets/other.7271.md

@@ -0,0 +1 @@
+- Refactor and annotate the BaseManager class and other files and functions used by the campaign platoons. (#7271)

engine/Sim/CAiBrain.lua

@@ -29,7 +29,7 @@ end
 --- Assigns units to a platoon
 ---@param platoon moho.platoon_methods | string Either a reference to a platoon, or the unique name of the platoon
 ---@param units Unit[]
----@param squad PlatoonSquads
+---@param squad PlatoonSquadType
 ---@param formation UnitFormations
 ---@return UnitFormations #Returns the name of the formation
 function CAiBrain:AssignUnitsToPlatoon(platoon, units, squad, formation)
@@ -406,12 +406,18 @@ end
 
 --- Returns platoon by unique name.
 ---
----@see moho.platoon_methods.UniquelyNamePlatoon To set the name.
+---@see moho.platoon_methods.UniquelyNamePlatoon # To set the name.
 ---@param name string
 ---@return Platoon?
 function CAiBrain:GetPlatoonUniquelyNamed(name)
 end
 
+--- `ArmyPool` is created by engine and contains all units for the army
+---@param name 'ArmyPool'
+---@return Platoon
+function CAiBrain:GetPlatoonUniquelyNamed(name)
+end
+
 --- Returns brain's platoons
 ---@return Platoon[]
 function CAiBrain:GetPlatoonsList()
@@ -509,7 +515,7 @@ end
 
 --- TODO.
 ---@param platoon Platoon
----@param squad PlatoonSquads
+---@param squad PlatoonSquadType
 ---@param alliance AllianceType
 ---@param compareType 'LeastDefended'|'Closest'|'Furthest'|'HighestValue'
 ---@param category EntityCategory
@@ -519,7 +525,7 @@ end
 
 --- TODO.
 ---@param platoon Platoon
----@param squad PlatoonSquads
+---@param squad PlatoonSquadType
 ---@param alliance AllianceType
 ---@param compareType 'LeastDefended'|'Closest'|'Furthest'|'HighestValue'
 ---@param category EntityCategory

lua/AI/AttackManager.lua

@@ -3,6 +3,12 @@ local Utilities = import("/lua/utilities.lua")
 local pairs, ipairs = pairs, ipairs
 local iscallable = iscallable
 
+local airCheckCategories = categories.AIR * categories.MOBILE - categories.TRANSPORTATION - categories.EXPERIMENTAL - categories.SCOUT
+local landCheckCategories = categories.LAND * categories.MOBILE - categories.ENGINEER - categories.EXPERIMENTAL - categories.SCOUT
+local navalCheckCategories = categories.NAVAL * categories.MOBILE - categories.EXPERIMENTAL
+local anyCheckCategories = categories.MOBILE - categories.ENGINEER - categories.TRANSPORTATION - categories.EXPERIMENTAL - categories.SCOUT
+
+
 -------------------------------------------------------------------------------------------------------------------------
 --- This is the AttackManager class that is used for campaign/coop
 --- Vanilla Supreme Commander (referred to as *SC1* from now on) used this along with the PBM for its skirmish AI as well
@@ -58,6 +64,7 @@ local iscallable = iscallable
 ---@field DestroyCallbacks FileFunctionRef[]|nil Table of functions called when the platoon is destroyed
 ---@field LocationType string Location from PBM -- used if you want to get units from pool
 ---@field PlatoonType "Air" | "Gate" | "Land" | "Sea" | "Any" MUST BE SET IF UsePool IS `true`
+---@field PlatoonAddFunctions FileFunctionRef[]
 ---@field UsePool boolean Bool to use pool or not. Defaults to `false`
 
 
@@ -72,7 +79,6 @@ local iscallable = iscallable
 ---@field AttackManagerState AttackManagerState Either 'ACTIVE' or 'PAUSED', used to check if the AM is active for an AI
 ---@field AMFormThread thread|nil
 AttackManager = ClassSimple {
-    brain = nil,
     NeedSort = false,
     PlatoonCount = { DefaultGroupAir = 0, DefaultGroupLand = 0, DefaultGroupSea = 0, },
 
@@ -240,7 +246,7 @@ AttackManager = ClassSimple {
     CheckAttackConditions = function(self, pltnInfo)
         for _, v in pairs(pltnInfo.AttackConditions) do
             if iscallable(v[1]) then
-                if not v[1](self.brain, unpack(v[2])) then
+                if not v[1](self.brain, unpack(v[2]--[[@as table]])) then
                     return false
                 end
             else
@@ -330,16 +336,16 @@ AttackManager = ClassSimple {
                 local checkCategory
                 -- Only T1-T3 aerial combat units
                 if v.PlatoonType == 'Air' then
-                    checkCategory = categories.AIR * categories.MOBILE - categories.TRANSPORTATION - categories.EXPERIMENTAL - categories.SCOUT
+                    checkCategory = airCheckCategories
                 -- Only T1-T3 surface combat units
                 elseif v.PlatoonType == 'Land' then
-                    checkCategory = categories.LAND * categories.MOBILE - categories.ENGINEER - categories.EXPERIMENTAL - categories.SCOUT
+                    checkCategory = landCheckCategories
                 -- Only T1-T3 naval combat units
                 elseif v.PlatoonType == 'Sea' then
-                    checkCategory = categories.NAVAL * categories.MOBILE - categories.EXPERIMENTAL
+                    checkCategory = navalCheckCategories
                 -- Only T1-T3 combined-arms combat units
                 elseif v.PlatoonType == 'Any' then
-                    checkCategory = categories.MOBILE - categories.ENGINEER - categories.TRANSPORTATION - categories.EXPERIMENTAL - categories.SCOUT
+                    checkCategory = anyCheckCategories
                 else
                     error('*AI WARNING: Invalid Platoon Type - ' .. v.PlatoonType, 2)
                 end
@@ -349,7 +355,7 @@ AttackManager = ClassSimple {
 
                 -- If the AM platoon has a base of origin, it will only grab ArmyPool units from near it
                 if v.LocationType then
-                    local location = false
+                    local location
                     for locNum, locData in self.brain.PBM.Locations do
                         if v.LocationType == locData.LocationType then
                             location = locData