Re-implement the Easy AI pt. 1 (#4858)

engine/Sim/CAiBrain.lua

@@ -21,7 +21,7 @@ function CAiBrain:AssignThreatAtPosition(position, threat, decay, threatType)
 end
 
 --- Assigns a unit to a platoon
----@param platoon Platoon | string Either a reference to a platoon, or the unique name of the platoon
+---@param platoon moho.platoon_methods | string Either a reference to a platoon, or the unique name of the platoon
 ---@param unit Unit
 ---@param squad PlatoonSquads
 ---@param formation UnitFormations
@@ -267,7 +267,9 @@ end
 function CAiBrain:GetHighestThreatPosition(ring, restriction, threatType, armyIndex)
 end
 
---- Returns a list of units that match the categories
+--- Returns a list of units that match the categories.
+---
+--- This function does **not** take into account intel.
 ---@param category EntityCategory
 ---@param needToBeIdle boolean
 ---@param requireBuilt boolean Appears to be not functional
@@ -346,7 +348,7 @@ end
 ---@param radius number in game units
 ---@param restriction boolean
 ---@param threatType BrainThreatType
----@param armyIndex number
+---@param armyIndex number?
 ---@return BrainPositionThreat[]
 function CAiBrain:GetThreatsAroundPosition(position, radius, restriction, threatType, armyIndex)
 end
@@ -357,14 +359,9 @@ end
 function CAiBrain:GetUnitBlueprint(bpName)
 end
 
---- Return list of units around position.
--- @param category Unit's category, example: categories.TECH2 .
--- @param position Table with position {x, y, z}.
--- @param radius Number in game units.
--- @param alliance Types: 'Ally', 'Enemy', 'Neutral'.
--- @return tblUnits Table containing units.
-
---- Returns the units around a position that match the categories
+--- Returns the units around a position that match the categories.
+---
+--- This function takes into account intel.
 ---@param category EntityCategory
 ---@param position Vector
 ---@param radius number
@@ -384,7 +381,9 @@ end
 function CAiBrain:GiveStorage(type, amount)
 end
 
---- TODO.
+--- Returns true when any engineer is building something of the given category
+---@param category EntityCategory
+---@return boolean
 function CAiBrain:IsAnyEngineerBuilding(category)
 end
 
@@ -394,16 +393,16 @@ function CAiBrain:IsOpponentAIRunning()
 end
 
 --- Creates a new platoon.
--- @param name or '', custom platoon name
--- @param aiPlan Plan to follow for this platoon or '', the function for the plan is in '/lua/platoon.lua'.
--- @return Platoon.
+---@param name string   # unique name for platoon
+---@param aiPlan string # to follow for this platoon or '', the function for the plan is in '/lua/platoon.lua'.
+---@return Platoon
 function CAiBrain:MakePlatoon(name, aiPlan)
 end
 
---- Return number of unit's categories being built.
--- @param entityCategoryOfBuildee Unit's category that is being built.
--- @param entityCategoryOfBuilder Unit's category of the unit building, example: categories.CONSTRUCTION .
--- @return Number.
+--- Returns number of units of a given category building units of another given category
+---@param entityCategoryOfBuildee EntityCategory # Category of unit that is being built
+---@param entityCategoryOfBuilder EntityCategory # Category of unit that is building
+---@return number
 function CAiBrain:NumCurrentlyBuilding(entityCategoryOfBuildee, entityCategoryOfBuilder)
 end
 

engine/Sim/CPlatoon.lua

@@ -20,7 +20,7 @@ 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
@@ -31,30 +31,33 @@ end
 function CPlatoon:CalculatePlatoonThreat(threatType, category)
 end
 
----@param threatType BrainThreatType Examples: 'AntiSurface', 'AntiAir', 'Overall'.
----@param category EntityCategory Unit's category, example: categories.TECH2 .
----@param position Vector Table with position {x, y, z}.
----@param radius number Radius in game units.
+---@param threatType BrainThreatType
+---@param category EntityCategory
+---@param position Vector
+---@param radius number
 ---@return number
 function CPlatoon:CalculatePlatoonThreatAroundPosition(threatType, category, position, radius)
 end
 
---- Returns true if squad can attack target unit.
+--- Returns true if squad can attack target unit. As an example: can this platoon attack a bomber?
 ---@param squad PlatoonSquadType
----@param target Unit Unit to check.
+---@param target Unit
 ---@return boolean
 function CPlatoon:CanAttackTarget(squad, target)
 end
 
---- TODO.
+---@deprecated
 ---@return boolean
 function CPlatoon:CanConsiderFormingPlatoon()
 end
 
 --- TODO.
 -- Example: local formIt = poolPlatoon:CanFormPlatoon(template, personality:GetPlatoonSize(), self.Location, radius)
----@return boolean
-function CPlatoon:CanFormPlatoon()
+---@param template table
+---@param size number
+---@param location Vector
+---@param radius number
+function CPlatoon:CanFormPlatoon(template, size, location, radius)
 end
 
 --- Destroys the platoon including all its units.
@@ -84,6 +87,7 @@ end
 
 --- TODO.
 -- Needs 4 parametrs.
+---@deprecated
 function CPlatoon:FindClosestUnitToBase()
 end
 
@@ -105,6 +109,7 @@ end
 --- Finds prioritized unit to attack for squad.
 -- Uses priorities set by SetPrioritizedTargetList function.
 -- Used for TMLs to find a pick a target in their range
+---@see `SetPrioritizedTargetList`
 ---@param squad PlatoonSquadType
 ---@param alliance AllianceType
 ---@param canAttack boolean true/false if the squad has to be able to attack the unit.
@@ -121,6 +126,7 @@ function CPlatoon:FormPlatoon()
 end
 
 --- TODO.
+---@return string
 function CPlatoon:GetAIPlan()
 end
 
@@ -147,8 +153,8 @@ end
 function CPlatoon:GetPlatoonLifetimeStats()
 end
 
---- Returns platoon position
--- @return Table with position {x, y, z}.
+--- Computes the average platoon position, returns {0,0,0} if the platoon has no units
+---@return Vector
 function CPlatoon:GetPlatoonPosition()
 end
 
@@ -158,8 +164,8 @@ end
 function CPlatoon:GetPlatoonUniqueName()
 end
 
---- Returns list of units in theh platoon.
--- @return Table containing units.
+--- Returns list of units in the platoon
+---@return Unit[]
 function CPlatoon:GetPlatoonUnits()
 end
 
@@ -229,7 +235,7 @@ end
 -- If squad is specified, moves only the squad.
 ---@param position Vector Table with position {x, y, z}.
 ---@param useTransports boolean true/false
----@param squad PlatoonSquadType
+---@param squad PlatoonSquadType?
 ---@return PlatoonCommand
 function CPlatoon:MoveToLocation(position, useTransports, squad)
 end
@@ -238,7 +244,7 @@ end
 -- If squad is specified, move only with the squad.
 ---@param target Unit Unit to move to.
 ---@param useTransports boolean true/false
----@param squad PlatoonSquadType
+---@param squad PlatoonSquadType?
 ---@return PlatoonCommand
 function CPlatoon:MoveToTarget(target, useTransports, squad)
 end
@@ -279,7 +285,7 @@ end
 --- Orders platoon to stop, cancels all commands.
 -- If squad is specified, stops only the squad.
 -- Cancels all commands.
----@param squad PlatoonSquadType
+---@param squad PlatoonSquadType?
 function CPlatoon:Stop(squad)
 end
 

lua/AI/AIBuilders/AIEconomicBuilders.lua

@@ -2733,4 +2733,4 @@ BuilderGroup {
             }
         }
     },
-}
+}

lua/AI/AIBuilders/AIIntelBuilders.lua

@@ -510,4 +510,4 @@ BuilderGroup {
             }
         }
     }
-}
+}