Annotations related to script tasks (#6596)

- Annotates `ScriptTask`s and related code.
  - All task scripts
  - Scry ability (Eye of Rhianne's ability)
    - `orders.lua`'s interaction with scripted abilities like Scry
    - The remote viewing unit class for Scry
- Whitespace formatting

---------

Co-authored-by: (Jip) Willem Wijnia <[email protected]>

changelog/snippets/other.6596.md

@@ -0,0 +1 @@
+- (#6596) Annotate files related to scripted tasks like the Scry ability of the Eye of Rhianne or unit Enhancements.

engine/Core/Blueprints/UnitBlueprint.lua

@@ -36,6 +36,9 @@
 -- read more here: https://wiki.faforever.com/en/Blueprints
 
 ---@class UnitBlueprint: EntityBlueprint
+--- Table keyed with a `ScriptTask`'s `TaskName` that determines the properties of the order button for that ability.
+--- The `OrderInfo.behavior` is overwritten in `orders.lua`.
+---@field Abilities table<string, OrderInfo>
 --- the number of build bots a Cybran builder has
 ---@field BuildBotTotal? number
 --- set to an integer that describes the unit's position in the list of build icons

engine/Library.lua

@@ -73,6 +73,7 @@ end
 function debug.allocatedsize(obj)
 end
 
+--- Returns a cached table of all table allocations tracked between calls of `debug.trackallocations(true)` and `debug.trackallocations(false)`.
 ---@return table<any, string>
 function debug.allocinfo()
 end

engine/Sim/CUnitScriptTask.lua

@@ -3,13 +3,15 @@
 ---@class moho.ScriptTask_Methods
 local CUnitScriptTask = {}
 
----
---  Set the AI result, success or fail
-function CUnitScriptTask:SetAIResult()
+--- Set the AI result, success (1) or fail (2)
+---@param result
+---| 1 # Success: Successfully carried out the order.
+---| 2 # Fail: Failed to carry out the order.
+function CUnitScriptTask:SetAIResult(result)
 end
 
----
---
+--- Get the unit this task was ordered to.
+---@return Unit
 function CUnitScriptTask:GetUnit()
 end
 

engine/User.lua

@@ -602,10 +602,37 @@ end
 function GetUnitCommandDataOfUnit(unit)
 end
 
---- Givens a `RULEUCC` type command, return the equivalent `UNITCOMMAND` command.
---- See `/lua/ui/game/commandgraphparams.lua#CommandGraphParams`.
----@param rule CommandCap
----@return string
+--- Given a `RULEUCC` type command, return the equivalent `UNITCOMMAND` command or "None" otherwise.  
+--- See `/lua/ui/game/commandgraphparams.lua#CommandGraphParams` or `UserUnitCommand`.
+--[[```
+             RULEUCC_Move = Move
+             RULEUCC_Stop = Stop
+           RULEUCC_Attack = Attack
+            RULEUCC_Guard = Guard
+           RULEUCC_Patrol = Patrol
+  RULEUCC_RetaliateToggle = None
+           RULEUCC_Repair = Repair
+          RULEUCC_Capture = Capture
+        RULEUCC_Transport = TransportUnloadUnits
+    RULEUCC_CallTransport = TransportLoadUnits
+             RULEUCC_Nuke = Nuke
+         RULEUCC_Tactical = Tactical
+         RULEUCC_Teleport = Teleport
+            RULEUCC_Ferry = Ferry
+RULEUCC_SiloBuildTactical = BuildSiloTactical
+    RULEUCC_SiloBuildNuke = BuildSiloNuke
+        RULEUCC_Sacrifice = Sacrifice
+            RULEUCC_Pause = Pause
+       RULEUCC_Overcharge = OverCharge
+             RULEUCC_Dive = Dive
+          RULEUCC_Reclaim = Reclaim
+    RULEUCC_SpecialAction = SpecialAction
+             RULEUCC_Dock = None
+           RULEUCC_Script = None
+          RULEUCC_Invalid = None
+```]]
+---@param rule EngineCommandCap
+---@return string | "None"
 function GetUnitCommandFromCommandCap(rule)
 end
 
@@ -810,24 +837,24 @@ end
 function IssueBlueprintCommandToUnit(unit, command, blueprintid, count, clear)
 end
 
----
----@param command any
----@param string any?
+--- Issue a command to the current selection. 
+---@param command UserUnitCommand # Will crash the game if not a valid command.
+---@param luaParams? table | string | number | boolean # Will crash the game if the table contains non-serializable types.
 ---@param clear boolean?
-function IssueCommand(command, string, clear)
+function IssueCommand(command, luaParams, clear)
 end
 
 ---
 ---@param clear boolean
 function IssueDockCommand(clear)
 end
 
----
+--- Issue a command to the given units.
 ---@param unitList UserUnit[]
----@param command string
----@param string? string
+---@param command UserUnitCommand # Will crash the game if not a valid command.
+---@param luaParams? table | string | number | boolean # Will crash the game if the table contains non-serializable types.
 ---@param clear? boolean
-function IssueUnitCommand(unitList, command, string, clear)
+function IssueUnitCommand(unitList, command, luaParams, clear)
 end
 
 --- Given a MS Windows char code, returns the Maui char code

engine/User/UserUnit.lua

@@ -6,49 +6,71 @@
 local UserUnit = {}
 
 ---@alias UserUnitCommand 
---- | 'UNITCOMMAND_BuildFactory' 
---- | 'UNITCOMMAND_BuildSilo'
---- | 'UNITCOMMAND_DestroySelf'
---- | 'UNITCOMMAND_KillSelf'
---- | 'UNITCOMMAND_AssistCommander'
---- | 'UNITCOMMAND_Upgrade'
---- | 'UNITCOMMAND_Land'
---- | 'UNITCOMMAND_Stop'
---- | 'UNITCOMMAND_Dive'
---- | 'UNITCOMMAND_OverCharge'
---- | 'UNITCOMMAND_Sacrifice'
---- | 'UNITCOMMAND_Capture'
---- | 'UNITCOMMAND_Dock'
---- | 'UNITCOMMAND_Repair'
---- | 'UNITCOMMAND_Reclaim'
---- | 'UNITCOMMAND_Guard'
---- | 'UNITCOMMAND_BuildMobile'
---- | 'UNITCOMMAND_BuildAssist'
---- | 'UNITCOMMAND_Teleport'
---- | 'UNITCOMMAND_Ferry'
---- | 'UNITCOMMAND_AssistMove'
---- | 'UNITCOMMAND_DetachFromTransport'
---- | 'UNITCOMMAND_TransportUnloadSpecificUnits'
---- | 'UNITCOMMAND_TransportUnloadUnits'
---- | 'UNITCOMMAND_TransportReverseLoadUnits'
---- | 'UNITCOMMAND_TransportLoadUnits'
---- | 'UNITCOMMAND_FormPatrol'
---- | 'UNITCOMMAND_Patrol'
---- | 'UNITCOMMAND_CoordinatedMove'
---- | 'UNITCOMMAND_FormMove'
---- | 'UNITCOMMAND_Move'
---- | 'UNITCOMMAND_Nuke'
---- | 'UNITCOMMAND_FormAggressiveMove'
---- | 'UNITCOMMAND_AggressiveMove'
---- | 'UNITCOMMAND_Script'
---- | 'UNITCOMMAND_Tactical'
---- | 'UNITCOMMAND_FormAttack'
---- | 'UNITCOMMAND_Retaliate'
---- | 'UNITCOMMAND_Attack'
+---| "UNITCOMMAND_BuildFactory"
+---| "UNITCOMMAND_BuildSilo"
+---| "UNITCOMMAND_DestroySelf"
+---| "UNITCOMMAND_KillSelf"
+---| "UNITCOMMAND_AssistCommander"
+---| "UNITCOMMAND_Upgrade"
+---| "UNITCOMMAND_Land"
+---| "UNITCOMMAND_Stop"
+---| "UNITCOMMAND_Dive"
+---| "UNITCOMMAND_OverCharge"
+---| "UNITCOMMAND_Sacrifice"
+---| "UNITCOMMAND_Capture"
+---| "UNITCOMMAND_Dock"
+---| "UNITCOMMAND_Repair"
+---| "UNITCOMMAND_Reclaim"
+---| "UNITCOMMAND_Guard"
+---| "UNITCOMMAND_BuildMobile"
+---| "UNITCOMMAND_BuildAssist"
+---| "UNITCOMMAND_Teleport"
+---| "UNITCOMMAND_Ferry"
+---| "UNITCOMMAND_AssistMove"
+---| "UNITCOMMAND_DetachFromTransport" # Does nothing?
+---| "UNITCOMMAND_TransportUnloadSpecificUnits"
+---| "UNITCOMMAND_TransportUnloadUnits"
+---| "UNITCOMMAND_TransportReverseLoadUnits"
+---| "UNITCOMMAND_TransportLoadUnits"
+---| "UNITCOMMAND_FormPatrol"
+---| "UNITCOMMAND_Patrol"
+---| "UNITCOMMAND_CoordinatedMove"
+---| "UNITCOMMAND_FormMove"
+---| "UNITCOMMAND_Move"
+---| "UNITCOMMAND_Nuke"
+---| "UNITCOMMAND_FormAggressiveMove"
+---| "UNITCOMMAND_AggressiveMove"
+---| "UNITCOMMAND_Script"
+---| "UNITCOMMAND_Tactical"
+---| "UNITCOMMAND_FormAttack"
+---| "UNITCOMMAND_Retaliate"
+---| "UNITCOMMAND_Attack"
+---| "Move"
+---| "Stop"
+---| "Attack"
+---| "Guard"
+---| "Patrol"
+---| "Repair"
+---| "Capture"
+---| "TransportUnloadUnits"
+---| "TransportLoadUnits"
+---| "Nuke"
+---| "Tactical"
+---| "Teleport"
+---| "Ferry"
+---| "BuildSiloTactical"
+---| "BuildSiloNuke"
+---| "Sacrifice"
+---| "Pause"
+---| "OverCharge"
+---| "Dive"
+---| "Reclaim"
+---| "SpecialAction"
+---| "None"
 
 ---@alias UserUnitBlueprintCommand
---- | 'UNITCOMMAND_Upgrade'
---- | 'UNITCOMMAND_BuildFactory'
+---| "UNITCOMMAND_Upgrade"
+---| "UNITCOMMAND_BuildFactory"
 
 ---@class UICommandInfo
 ---@field type 'Teleport' | 'Move' | string

lua/RemoteViewing.lua

@@ -7,11 +7,29 @@
 --**
 --**  Copyright © 2007 Gas Powered Games, Inc.  All rights reserved.
 --****************************************************************************
+
 local VizMarker = import("/lua/sim/vizmarker.lua").VizMarker
 
 -- TODO: make sure each new instance is using a previous metatable
+
+-- TODO: Fix the RemoteViewingUnit class annotation always taking definitions from the Unit class instead of the base class.
+
+---@class RemoteViewingData
+---@field RemoteViewingFunctions table
+---@field DisableCounter number
+---@field IntelButton boolean
+---@field Satellite VizMarker
+---@field PendingVisibleLocation Vector
+---@field VisibleLocation Vector
+
+---@generic T: Unit
+---@param SuperClass T | Unit
+---@return T | RemoteViewingUnit
 function RemoteViewing(SuperClass)
+    ---@class RemoteViewingUnit: Unit
+    ---@field RemoteViewingData RemoteViewingData
     return Class(SuperClass) {
+        ---@param self RemoteViewingUnit
         OnCreate = function(self)
             SuperClass.OnCreate(self)
             self.RemoteViewingData = {}
@@ -20,12 +38,19 @@ function RemoteViewing(SuperClass)
             self.RemoteViewingData.IntelButton = true
         end,
 
-        OnStopBeingBuilt = function(self,builder,layer)
+        ---@param self RemoteViewingUnit
+        ---@param builder Unit
+        ---@param layer Layer
+        OnStopBeingBuilt = function(self, builder, layer)
             self.Sync.Abilities = self:GetBlueprint().Abilities
             self:SetMaintenanceConsumptionInactive()
-            SuperClass.OnStopBeingBuilt(self,builder,layer)
+            SuperClass.OnStopBeingBuilt(self, builder, layer)
         end,
 
+        ---@param self RemoteViewingUnit
+        ---@param instigator Unit
+        ---@param type DamageType
+        ---@param overkillRatio number
         OnKilled = function(self, instigator, type, overkillRatio)
             SuperClass.OnKilled(self, instigator, type, overkillRatio)
             if self.RemoteViewingData.Satellite then
@@ -34,18 +59,21 @@ function RemoteViewing(SuperClass)
             self:SetMaintenanceConsumptionInactive()
         end,
 
+        ---@param self RemoteViewingUnit
         DisableRemoteViewingButtons = function(self)
             self.Sync.Abilities = self:GetBlueprint().Abilities
             self.Sync.Abilities.TargetLocation.Active = false
             self:RemoveToggleCap('RULEUTC_IntelToggle')
         end,
 
+        ---@param self RemoteViewingUnit
         EnableRemoteViewingButtons = function(self)
             self.Sync.Abilities = self:GetBlueprint().Abilities
             self.Sync.Abilities.TargetLocation.Active = true
             self:AddToggleCap('RULEUTC_IntelToggle')
         end,
 
+        ---@param self RemoteViewingUnit
         TargetLocationThread = function(self)
             local Cost = CreateEconomyEvent(self, self:GetBlueprint().Economy.InitialRemoteViewingEnergyDrain * (self.EnergyMaintAdjMod or 1), 0, 1, self.SetWorkProgress)
             WaitFor(Cost)
@@ -57,6 +85,8 @@ function RemoteViewing(SuperClass)
             self:CreateVisibleEntity()
         end,
 
+        ---@param self RemoteViewingUnit
+        ---@param location Vector
         OnTargetLocation = function(self, location)
             if self.RemoteViewingData.PendingVisibleLocation then
                 self.RemoteViewingData.PendingVisibleLocation = location
@@ -65,7 +95,8 @@ function RemoteViewing(SuperClass)
                 self:ForkThread(self.TargetLocationThread)
             end
         end,
-
+
+        ---@param self RemoteViewingUnit
         CreateVisibleEntity = function(self)
             -- Only give a visible area if we have a location and intel button enabled
             if not self.RemoteViewingData.VisibleLocation then
@@ -94,7 +125,7 @@ function RemoteViewing(SuperClass)
                 else
                     -- Move and reactivate old visible area
                     if not self.RemoteViewingData.Satellite:BeenDestroyed() then
-                        Warp( self.RemoteViewingData.Satellite, self.RemoteViewingData.VisibleLocation )
+                        Warp(self.RemoteViewingData.Satellite, self.RemoteViewingData.VisibleLocation)
                         self.RemoteViewingData.Satellite:EnableIntel('Omni')
                         self.RemoteViewingData.Satellite:EnableIntel('Radar')
                         self.RemoteViewingData.Satellite:EnableIntel('Vision')
@@ -109,6 +140,7 @@ function RemoteViewing(SuperClass)
             end
         end,
 
+        ---@param self RemoteViewingUnit
         DisableVisibleEntity = function(self)
             -- visible entity already off
             if self.RemoteViewingData.DisableCounter > 1 then return end
@@ -121,6 +153,8 @@ function RemoteViewing(SuperClass)
             end
         end,
 
+        ---@param self RemoteViewingUnit
+        ---@param intel IntelType
         OnIntelEnabled = function(self, intel)
             -- Make sure the button is only calculated once rather than once per possible intel type
             if not self.RemoteViewingData.IntelButton then
@@ -131,6 +165,8 @@ function RemoteViewing(SuperClass)
             SuperClass.OnIntelEnabled(self, intel)
         end,
 
+        ---@param self RemoteViewingUnit
+        ---@param intel IntelType
         OnIntelDisabled = function(self, intel)
             -- make sure button is only calculated once rather than once per possible intel type
             if self.RemoteViewingData.IntelButton then
@@ -141,6 +177,7 @@ function RemoteViewing(SuperClass)
             SuperClass.OnIntelDisabled(self, intel)
         end,
 
+        ---@param self RemoteViewingUnit
         DisableResourceMonitor = function(self)
             WaitSeconds(0.5)
             local fraction = self:GetResourceConsumed()
@@ -155,6 +192,7 @@ function RemoteViewing(SuperClass)
             end
         end,
 
+        ---@param self RemoteViewingUnit
         EnableResourceMonitor = function(self)
             local recharge = self:GetBlueprint().Intel.ReactivateTime or 10
             WaitSeconds(recharge)

lua/abilitydefinition.lua

@@ -2,6 +2,10 @@
 -- Ability Definitions
 --
 
+--- Defines the default behavior of ability buttons in `orders.lua` for each `ScriptTask`'s `TaskName`.  
+--- The `OrderInfo` here has the `OrderInfo` of `UnitBlueprint.Abilities` merged onto it.  
+--- The `OrderInfo.behavior` is overwritten in `orders.lua`.
+---@type table<string, OrderInfo>
 abilities = {
     ['TargetLocation'] = {
         preferredSlot = 8,