Add in remaining blueprint annotations (FAForever#4513)

engine/Core.lua

@@ -1,6 +1,9 @@
 ---@meta
 ---@diagnostic disable: lowercase-global
 
+---@class FileName: string, stringlib
+---@operator concat(FileName | string): FileName
+
 ---@class Quaternion
 ---@field [1] number
 ---@field [2] number
@@ -27,130 +30,137 @@
 ---@alias Army string | number
 ---@alias Language "cn" | "cz" | "de" | "es" | "fr" | "it" | "pl" | "ru" | "tw" | "tzm" | "us"
 
+-- note that these object span both the sim and user states
+---@alias GoalObject moho.manipulator_methods | EconomyEvent | Camera
+
 ---@unknown
 function AITarget()
 end
 
---- Set the audio language
+--- sets the audio language
 ---@param language Language
 function AudioSetLanguage(language)
 end
 
---- Returns the last component of a path
----@param fullPath string
+--- returns the last component of a path
+---@param fullPath FileName
 ---@param stripExtension boolean?
+---@return FileName
 function Basename(fullPath, stripExtension)
 end
 
---- Likely used for debugging, but the use is unknown
+--- likely used for debugging, but the use is unknown
 ---@unknown
 function BeginLoggingStats()
 end
 
---- Called during blueprint loading to update the loading animation
+--- called during blueprint loading to update the loading animation
 function BlueprintLoaderUpdateProgress()
 end
 
---- Create an empty prefetch set
+--- creates an empty prefetch set
 ---@return moho.CPrefetchSet
 function CreatePrefetchSet()
 end
 
---- Returns the current running thread
+--- returns the currently running thread
 ---@return thread?
 function CurrentThread()
 end
 
---- Returns the directory name
+--- returns the directory name
 ---@param fullPath FileName
 ---@return string
 function Dirname(fullPath)
 end
 
---- Returns all files in the directory that matches the pattern
+--- returns all files in the directory that matches the pattern
 ---@param directory FileName
 ---@param pattern string
 ---@return FileName[]
 function DiskFindFiles(directory,  pattern)
 end
 
---- Returns a table of information for the given file, or false if the file doesn't exist 
+--- returns a table of information for the given file, or `false` if the file doesn't exist 
 ---@param filename FileName
 ---@return table | false
 function DiskGetFileInfo(filename)
 end
 
---- Converts a system path to a local path (based on the init file directories), returns the path if it is already local
+--- converts a system path to a local path (based on the init file directories),
+--- returns the path if it is already local
 ---@param SysOrLocalPath FileName
 ---@return FileName
 function DiskToLocal(SysOrLocalPath)
 end
 
----End logging stats and optionally exit app
+--- stops logging stats and optionally exits the application
 ---@param exit boolean
 function EndLoggingStats(exit)
 end
 
---- Return true if a unit category contains this unit
+--- returns true if a unit category contains this unit
 ---@param category EntityCategory
 ---@param unit Unit | UserUnit
 function EntityCategoryContains(category, unit)
 end
 
---- Checks for the empty category
+--- checks if the category is the empty category
 ---@param category EntityCategory
 ---@return boolean
 function EntityCategoryEmpty(category)
 end
 
 ---@overload fun(units: UserUnit[]): UserUnit[]
---- Filter a list of units to only those found in the category
+--- filters a list of units to only those found in the category
 ---@param category EntityCategory
 ---@param units Unit[]
 ---@return Unit[]
 function EntityCategoryFilterDown(category, units)
 end
 
---- Computes a list of unit blueprint names that match the categories
+--- computes a list of unit blueprint names that match the categories
 ---@param category EntityCategory
 ---@return string[]
 function EntityCategoryGetUnitList(category)
 end
 
---- Returns an ordered list of named colors available for a `Color` instead of using a hexcode
+--- returns an ordered list of named colors available for a `Color` instead of using a hexcode
 ---@return EnumColor[]
 function EnumColorNames()
 end
 
---- Converts euler angles to a quaternion
+--- converts an Euler angle to a quaternion
 ---@param roll number
 ---@param pitch number
 ---@param yaw number
 ---@return Quaternion
 function EulerToQuaternion(roll, pitch, yaw)
 end
 
---- Collapse all intermediate `/./` or `/../` directory names from a path
+--- collapses all relative `/./` or `/../` directory names from a path
 ---@param fullPath FileName
 ---@return FileName
 function FileCollapsePath(fullPath)
 end
 
---- Creates a new thread, passing all additional arguments to the callback
+--- creates a new thread, passing all additional arguments to the callback
 ---@param callback function
 ---@param ... any
 ---@return thread
 function ForkThread(callback, ...)
 end
 
---- Get the blueprint of an object
+--- gets the blueprint of an object
 ---@overload fun(entity: Entity): EntityBlueprint
 ---@overload fun(mesh: Mesh): MeshBlueprint
 ---@overload fun(effect: moho.IEffect): EffectBlueprint
 ---@overload fun(projectile: Projectile): ProjectileBlueprint
 ---@overload fun(prop: Prop): PropBlueprint
 ---@overload fun(unit: UserUnit | Unit): UnitBlueprint
 ---@overload fun(weapon: Weapon): WeaponBlueprint
+---@param object Object
+---@return Blueprint
 function GetBlueprint(object)
 end
 
@@ -177,8 +187,7 @@ end
 function GetMovieDuration(localFileName)
 end
 
----
----@param id UnitId
+---@param id EntityId
 ---@return UserUnit | Unit
 function GetUnitById(id)
 end
@@ -188,12 +197,10 @@ end
 function GetVersion()
 end
 
----
 ---@param language Language
 function HasLocalizedVO(language)
 end
 
----
 ---@param army1 number
 ---@param army2 number
 ---@return boolean
@@ -206,14 +213,12 @@ end
 function IsDestroyed(entity)
 end
 
----
 ---@param army1 number
 ---@param army2 number
 ---@return boolean
 function IsEnemy(army1, army2)
 end
 
----
 ---@param army1 number
 ---@param army2 number
 ---@return boolean
@@ -357,7 +362,6 @@ end
 function SessionIsReplay()
 end
 
----
 ---@param armyIndex number index or -1
 function SetFocusArmy(armyIndex)
 end
@@ -395,7 +399,7 @@ end
 function STR_itox(int)
 end
 
----  Converts a hexidecimal string to an integer
+--- Converts a hexidecimal string to an integer
 ---@param string string
 ---@return number
 function STR_xtoi(string)
@@ -511,18 +515,19 @@ end
 function WARN(out, ...)
 end
 
---- Suspends the thread until the manipulator reaches its goal
----@param manipulator moho.manipulator_methods | EconomyEvent
+--- suspends the thread until the object reaches its goal
+---@param manipulator GoalObject
 function WaitFor(manipulator)
 end
 
---- Run another script. The environment table, if given, will be used for the script's global variables.
----@param script string
+--- Runs another script file. The environment table, if given,
+--- will be used for the script's global variables.
+---@param script FileName
 ---@param env? table
 function doscript(script,  env)
 end
 
---- Returns if the given resource file exists
+--- returns true if the given resource file exists
 ---@param name FileName
 function exists(name)
 end

engine/Core/Blueprints/BeamBlueprint.lua

@@ -4,9 +4,9 @@
 ---@field Length number                Total length of beam
 ---@field Lifetime number              Lifetime of the emitter
 ---@field Thickness number             Thickness of the beam
----@field Filename FileName            Filename of texture
+---@field TextureName FileName         Filename of texture
 ---@field StartColor NamedQuaternion   RGBA start color of beam
 ---@field EndColor NamedQuaternion     RGBA end color of beam
----@field UShift  number               U Texture shift of beam texture
----@field VShift  number               V Texture shift of beam texture
----@field RepeatRate number            How often the texture repeats per ogrid blendmode of this beam
+---@field UShift number                U Texture shift of beam texture
+---@field VShift number                V Texture shift of beam texture
+---@field RepeatRate number            How often the texture repeats per ogrid blendmode of this beam

engine/Core/Blueprints/Blueprint.lua

@@ -1,11 +1,32 @@
 ---@meta
 
+---@alias BlueprintId string
+
 ---@class Blueprint
----@field BlueprintId? string BlueprintId is used for modding an existing blueprint. An example for usage is BlueprintId = 'uel0101' which would be the UEF Land Scout.
----@field Merge? boolean      Merge is used for modding an existing blueprint. With Merge = 'true' the BlueprintId must be set.
----@field Source? string
+--- The unique id of this blueprint. For units, this field is autogenerated from `Source` if not
+--- already present. If a blueprint is loaded that has the same id as one already loaded, it
+--- overrides it unless `Merge = true` is also set. This is typically what happens for mods, e.g.
+---     BlueprintId = "uel0101",
+---     Merge = true,
+--- would let you change the blueprint of the Snoop UEF Land Scout without needing to add everything
+--- in the original definition (which could change or be modified by other mods).
+---@field BlueprintId BlueprintId
+--- Setting `Merge = true` will make the blueprint definition merge with an already existing one
+--- given by `BlueprintId` (which must also be set to an existing blueprint id).
+---@field Merge? boolean
+--- the file the blueprint was originally defined in
+---@field Source string
+
+---@alias SoundLodCutoff
+---| "DefaultLodCutoff"
+---| "UnitMove_LodCutoff"
+---| "Weapon_LodCutoff"
+---| "WeaponBig_LodCutoff"
 
 ---@class SoundBlueprint
+--- which sound bank to use
 ---@field Bank string
+--- the sound cue inside of the sound bank to use
 ---@field Cue string
----@field LodCutoff string
+--- unknown usage
+---@field LodCutoff SoundLodCutoff

engine/Core/Blueprints/EffectBlueprint.lua

@@ -1,7 +1,6 @@
 ---@meta
 
 ---@class EffectBlueprint : Blueprint
----@field BlueprintId  string  Blueprint ID
 ---@field HighFidelity boolean Allowed in high fidelity
 ---@field MedFidelity  boolean Allowed in medium fidelity
 ---@field LowFidelity  boolean Allowed in low fidelity