Merge branch 'code-formating-Units-V1' of https://github.com/MrRowey/fa…

… into pr/5759

changelog/snippets/balance.6179.md

@@ -0,0 +1 @@
+- (#6179) Increase Ilshavoh's max turn rate from 75 to 90 and on the spot turn rate from 45 to 90.

changelog/snippets/fix.6182.md

@@ -0,0 +1 @@
+- (#6182) Enable the target bones for the Soothsayer.

changelog/snippets/other.6181.md

@@ -0,0 +1 @@
+- (#6181) Annotate fields and functions related to bomb projectiles.

engine/Core/Blueprints/ProjectileBlueprint.lua

@@ -66,7 +66,7 @@
 ---@field LeadTarget boolean
 --- Whether projectiles should try to stay underwater. Applies only to tracking projectiles.
 ---@field StayUnderwater boolean
---- if the projectile is initially affected by gravity
+--- if the projectile is initially affected by gravity (-4.9 ogrids/second/second)
 ---@field UseGravity boolean
 --- projectile will detonate when going above this height above ground
 ---@field DetonateAboveHeight number
@@ -133,7 +133,8 @@
 ---@field MaxZigZag number
 --- frequency of zig-zag directional changes, in seconds
 ---@field ZigZagFrequency number
---- realistic free fall ordinance type weapon
+--- When true and weapon muzzle velocity is 0, the projectile's horizontal velocity is set in the direction of the target with the speed of the weapon firing the projectile.
+--- Used for realistic free fall ordinance type weapons like bombs
 ---@field RealisticOrdinance boolean
 --- bombs that always drop stright down
 ---@field StraightDownOrdinance boolean

engine/Core/Blueprints/WeaponBlueprint.lua

@@ -51,7 +51,7 @@
 ---@field BeamLifetime number
 --- if the weapon will only fire when underwater
 ---@field BelowWaterFireOnly? boolean
---- threshold to release point before releasing ordnance
+--- Distance from bomb firing solution's position to the target's position within which the weapon will fire 
 ---@field BombDropThreshold? number
 --- information about the bonuses added to the weapon when it reaches a specific veterancy level
 ---@field Buffs BlueprintBuff[]

engine/Sim/Projectile.lua

@@ -90,7 +90,7 @@ end
 function Projectile:SetAcceleration(accel)
 end
 
---- Define the ballistic acceleration value, increases velocity in the current direction.
+--- Set the vertical (gravitational) acceleration of the projectile. Default is -4.9, which is expected by the engine's weapon targeting and firing
 ---@param accel number
 function Projectile:SetBallisticAcceleration(accel)
 end

lua/AI/OpAI/BaseManager.lua

@@ -160,6 +160,67 @@ local BuildingCounterDefaultValues = {
     },
 }
 
+--- Failsafe callback function when a structure marked for needing an upgrade starts building something
+--- If that 'something' is the upgrade itself, create a callback for the upgrade
+---@param unit Unit
+---@param unitBeingBuilt Unit
+function FailSafeStructureOnStartBuild(unit, unitBeingBuilt)
+	-- If we are in the upgrading state, then it's the upgrade we want under normal circumstances.
+	-- We don't use different upgrades paths for coop, only that of the original SCFA (no Support Factory upgrade paths whatsoever)
+	-- If you decide to mess around with AI armies in cheat mode, and order a newly added upgrade path instead anyway, then any mishaps happening afterwards is on you!
+	if unit:IsUnitState('Upgrading') then
+		unitBeingBuilt.UnitName = unit.UnitName
+		unitBeingBuilt.BaseName = unit.BaseName
+
+		-- Add callback when the upgrade is finished
+		if not unitBeingBuilt.AddedFinishedCallback then
+			unitBeingBuilt:AddUnitCallback(FailSafeUpgradeOnStopBeingBuilt, 'OnStopBeingBuilt')
+			unitBeingBuilt.AddedFinishedCallback = true
+		end
+	end
+end
+
+--- Failsafe function that will upgrade factories, radar, etc. to next level
+---@param unit Unit
+---@param upgradeID Upgrade Blueprint
+function FailSafeUpgradeBaseManagerStructure(unit, upgradeID)
+	-- Add callback when the structure starts building something
+	if not unit.AddedUpgradeCallback then
+		unit:AddOnStartBuildCallback(FailSafeStructureOnStartBuild)
+		unit.AddedUpgradeCallback = true
+	end
+
+    IssueUpgrade({unit}, upgradeID)
+	unit.SetToUpgrade = true
+end
+
+--- Failsafe callback function when a structure upgrade is finished building
+--- Updates the ScenarioInfo.UnitNames table with the new unit, and upgrades further if needed
+---@param unit Unit
+function FailSafeUpgradeOnStopBeingBuilt(unit)
+	local aiBrain = unit.Brain
+	local bManager = aiBrain.BaseManagers[unit.BaseName]
+
+	if bManager then
+		local armyIndex = aiBrain:GetArmyIndex()
+		ScenarioInfo.UnitNames[armyIndex][unit.UnitName] = unit
+
+		local factionIndex = aiBrain:GetFactionIndex()
+		local upgradeID = aiBrain:FindUpgradeBP(unit.UnitId, UpgradeTemplates.StructureUpgradeTemplates[factionIndex])
+
+		-- Check if our structure can even upgrade to begin with
+		if upgradeID then
+			-- Check if the BM is supposed to upgrade this structure further
+			for index, structure in bManager.UpgradeTable do
+				-- If the names match, and the IDs don't, we need to upgrade
+				if unit.UnitName == structure.UnitName and unit.UnitId ~= structure.FinalUnit and not unit.SetToUpgrade then
+					FailSafeUpgradeBaseManagerStructure(unit, upgradeID)
+				end
+			end
+		end
+	end
+end
+
 ---@alias Enhancement string --TODO
 
 ---@class LevelName
@@ -213,7 +274,7 @@ BaseManager = ClassSimple {
         self.NumPermanentAssisting = 0
         self.PermanentAssistCount = 0
         self.PermanentAssisters = {}
-        self.MaximumConstructionEngineers = 2
+        self.MaximumConstructionEngineers = ScenarioInfo.Options.Difficulty or 3
 
         self.BuildingCounterData = {
             Default = true,
@@ -222,30 +283,33 @@ BaseManager = ClassSimple {
         self.BuildTable = {}
         self.ConstructionEngineers = {}
         self.ExpansionBaseData = {}
+
+		-- Commented out unused states, these were only found here throughout the FAF repo
+		-- We can re-enable them if corresponding functionalities are created, but right now there are none
         self.FunctionalityStates = {
-            AirAttacks = true,
+            --AirAttacks = true,
             AirScouting = false,
             AntiAir = true,
             Artillery = true,
             BuildEngineers = true,
             CounterIntel = true,
-            EngineerReclaiming = true,
+            --EngineerReclaiming = true,
             Engineers = true,
             ExpansionBases = false,
             Fabrication = true,
             GroundDefense = true,
             Intel = true,
-            LandAttacks = true,
+            --LandAttacks = true,
             LandScouting = false,
             Nukes = false,
             Patrolling = true,
-            SeaAttacks = true,
+            --SeaAttacks = true,
             Shields = true,
             TMLs = true,
             Torpedos = true,
             Walls = true,
 
-            Custom = {},
+            --Custom = {},
         }
         self.LevelNames = {}
         self.OpAITable = {}
@@ -1079,23 +1143,23 @@ BaseManager = ClassSimple {
         self:SetUnitUpgrades(upgradeTable, 'DefaultSACU', startActive)
     end,
 
-    ---@param self BaseManager
+    --- Failsafe thread that will periodically loop through existing units that have been converted to lower tech level units so they can be built (ie. HQ factories)
+	--- If their unit IDs don't match the one set in the save.lua file, a failsafe function will be called to check if they are idle, so an upgrade can be started
+	---@param self BaseManager
     UpgradeCheckThread = function(self)
         local armyIndex = self.AIBrain:GetArmyIndex()
         while true do
             if self.Active then
                 for k, v in self.UpgradeTable do
                     local unit = ScenarioInfo.UnitNames[armyIndex][v.UnitName]
-                    if unit and not unit.Dead then
-                        -- Structure upgrading should take priority, so the check for unit.UnitBeingBuilt is not needed. This check is a lot more reliable to get factories to upgrade
-                        if unit.UnitId ~= v.FinalUnit and not unit:IsBeingBuilt() and not unit:IsUnitState('Upgrading') then
-                            self:ForkThread(self.BaseManagerUpgrade, unit, v.UnitName)
-                        end
+					-- Check if the structure exists, and needs to upgrade
+                    if unit and not unit.Dead and unit.UnitId ~= v.FinalUnit then
+                        --self:ForkThread(self.BaseManagerUpgrade, unit, v.UnitName)
+						self:BaseManagerUpgrade(unit, v.UnitName)
                     end
                 end
             end
-            local waitTime = Random(3, 5)
-            WaitSeconds(waitTime)
+            WaitSeconds(15)
         end
     end,
 
@@ -1236,33 +1300,25 @@ BaseManager = ClassSimple {
         end
     end,
 
-    -- Thread that will upgrade factories, radar, etc to next level
-    ---@param self BaseManager
+    --- Failsafe function that will upgrade factories, radar, etc. to next level if the initial upgrade order executed via build callbacks failed somehow
+	---@param self BaseManager
     ---@param unit Unit
     ---@param unitName string
-    BaseManagerUpgrade = function(self, unit, unitName)
-        local aiBrain = unit:GetAIBrain()
-        local factionIndex = aiBrain:GetFactionIndex()
-        local armyIndex = aiBrain:GetArmyIndex()
-        local upgradeID = aiBrain:FindUpgradeBP(unit.UnitId, UpgradeTemplates.StructureUpgradeTemplates[factionIndex])
-        if upgradeID then
-            IssueToUnitClearCommands(unit)
-            IssueUpgrade({ unit }, upgradeID)
-        end
-
-        local upgrading = true
-        local newUnit = false
-        while not unit.Dead and upgrading do
-            WaitSeconds(3)
-            upgrading = false
-            if unit and not unit.Dead then
-                if not newUnit then
-                    newUnit = unit.UnitBeingBuilt
-                end
-                upgrading = true
-            end
-        end
-        ScenarioInfo.UnitNames[armyIndex][unitName] = newUnit
+	BaseManagerUpgrade = function(self, unit, unitName)
+		-- If we were set to upgrade, and we're being built, or busy building something, return
+		if unit.SetToUpgrade and (unit:IsUnitState('Upgrading') or unit:IsUnitState('Building') or unit:IsUnitState('BeingBuilt') or unit:GetNumBuildOrders(categories.ALLUNITS) > 0) then
+			return
+		end
+
+		local aiBrain = self.AIBrain
+		local factionIndex = aiBrain:GetFactionIndex()
+		local upgradeID = aiBrain:FindUpgradeBP(unit.UnitId, UpgradeTemplates.StructureUpgradeTemplates[factionIndex])
+
+		if upgradeID then
+			FailSafeUpgradeBaseManagerStructure(unit, upgradeID)
+		else
+			WARN("BM Failsafe upgrade error: Couldn't find valid upgrade ID for unit named: " .. tostring(unitName) .. ", part of: " .. tostring(unit.BaseName))
+		end
     end,
 
     ---@param self BaseManager
@@ -1276,6 +1332,7 @@ BaseManager = ClassSimple {
         return true
     end,
 
+	--- The following "template" variables were removed due to them not being used at all: AmountNeeded, AmountWanted, CloseToBuilder
     ---@param self BaseManager
     ---@param groupName string
     ---@param addName string
@@ -1313,15 +1370,13 @@ BaseManager = ClassSimple {
                         for k, section in template do -- Check each section of the template for the right type
                             if section[1][1] == buildList[1] then
                                 table.insert(section, unitPos) -- Add position of new unit if found
-                                list[unit.buildtype].AmountWanted = list[unit.buildtype].AmountWanted + 1 -- Increment num wanted if found
                                 inserted = true
                                 break
                             end
                         end
                         if not inserted then -- If section doesn't exist create new one
                             table.insert(template, { { buildList[1] }, unitPos }) -- add new build type to list with new unit
-                            list[unit.buildtype] = { StructureType = buildList[1], StructureCategory = unit.buildtype,
-                                AmountNeeded = 0, AmountWanted = 1, CloseToBuilder = nil } -- add new section of build list with new unit type information
+                            list[unit.buildtype] = { StructureType = buildList[1], StructureCategory = unit.buildtype }
                         end
                         break
                     end
@@ -2083,4 +2138,4 @@ function CreateBaseManager(brain, baseName, markerName, radius, levelTable)
     end
 
     return bManager
-end
+end