update annotations for engine runtime defined fields

.vscode/settings.json

@@ -6,12 +6,16 @@
     "doscript": "require",
     "lazyimport": "require"
   },
-  "Lua.runtime.version": "Lua 5.1",
-  "Lua.telemetry.enable": false,
+  "Lua.runtime.version": "LuaFA",
   "Lua.workspace.checkThirdParty": false,
   "Lua.runtime.path": ["/?"],
   "Lua.runtime.plugin": ".vscode/fa-plugin.lua",
-  "Lua.workspace.ignoreDir": [".vscode", "loc", "*.bp", "lua/ui/lobby/changelog/generated/*"],
+  "Lua.workspace.ignoreDir": [
+    ".vscode",
+    "loc",
+    "*.bp",
+    "lua/ui/lobby/changelog/generated/*"
+  ],
   "[lua]": {
     "editor.wordBasedSuggestions": "off"
   },
@@ -25,10 +29,10 @@
   "Lua.completion.autoRequire": false,
   "Lua.diagnostics.globals": ["ScenarioInfo", "__moduleinfo"],
   "Lua.format.defaultConfig": {
-    "max_line_length": "unset",
+    "max_line_length": "unset"
   },
   "[markdown]": {
-    "editor.tabSize": 2,
+    "editor.tabSize": 2
   },
 
   // used for grammar checks of changelog

engine/AnnotationCommon.lua

@@ -9,7 +9,7 @@
 ---@class CScriptObject : userdata
 
 ---@class InternalObject : Destroyable
----@field _c_object CScriptObject
+---@field _c_object EngineDefinedField <CScriptObject>
 
 ---@class Destroyable
 local Destroyable = {}

engine/Core/Blueprints/Blueprint.lua

@@ -1,5 +1,8 @@
 ---@meta
 
+-- nilable alias used for fields that are defined in the engine (purely to prevent undefined field errors in the lua language server)
+---@alias EngineDefinedField<T> T | nil
+
 ---@alias BlueprintId string
 
 ---@class Blueprint
@@ -10,12 +13,12 @@
 ---     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
+---@field BlueprintId EngineDefinedField <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
+---@field Source EngineDefinedField <string>
 
 ---@alias SoundLodCutoff
 ---| "DefaultLodCutoff"
@@ -29,4 +32,4 @@
 --- the sound cue inside of the sound bank to use
 ---@field Cue string
 --- unknown usage
----@field LodCutoff SoundLodCutoff
+---@field LodCutoff EngineDefinedField <SoundLodCutoff>

engine/Core/Blueprints/EntityBlueprint.lua

@@ -14,50 +14,50 @@
 --- list of categories to remove during blueprint loading (for merge blueprints)
 ---@field DelCategories? CategoryName[]
 --- shape to use for collisions with the entity
----@field CollisionShape CollisionShape
+---@field CollisionShape EngineDefinedField <CollisionShape>
 --- the desired maximum number of shooters taking shots at the entity
----@field DesiredShooterCap number
+---@field DesiredShooterCap EngineDefinedField <number>
 --- Unit footprint. If absent, uses the `SizeX` and `SizeZ` fields.
 ---@field Footprint? FootprintBlueprint
 --- component X,X of inertia tensor
----@field InertiaTensorX number
+---@field InertiaTensorX EngineDefinedField <number>
 --- component Y,Y of inertia tensor
----@field InertiaTensorY number
+---@field InertiaTensorY EngineDefinedField <number>
 --- component Z,Z of inertia tensor
----@field InertiaTensorZ number
+---@field InertiaTensorZ EngineDefinedField <number>
 --- height of lifebar in OGrids
 ---@field LifeBarHeight number
 --- vertical offset of the lifebar from the entity
 ---@field LifeBarOffset number
 --- if the life bar is rendered or not
----@field LifeBarRender boolean
+---@field LifeBarRender EngineDefinedField <boolean>
 --- size of lifebar in OGrids
 ---@field LifeBarSize number
 --- module defining entity's class
----@field ScriptModule FileName
+---@field ScriptModule EngineDefinedField <FileName>
 --- name of entity's class
----@field ScriptClass string
+---@field ScriptClass EngineDefinedField <string>
 --- x offset from center of the entity's selection box
----@field SelectionCenterOffsetX number
+---@field SelectionCenterOffsetX EngineDefinedField <number>
 --- y offset from center of the entity's selection box
----@field SelectionCenterOffsetY number
+---@field SelectionCenterOffsetY EngineDefinedField <number>
 --- y offset from center of the entity's selection box
----@field SelectionCenterOffsetZ number
+---@field SelectionCenterOffsetZ EngineDefinedField <number>
 --- how far to reduce the top of the collision box for selection (defaults to 0.5)
 ---@field SelectionYOffset? number
 --- Scale the mesh on the X axis by this much when we perform our mouse over entity test
----@field SelectionMeshScaleX number
+---@field SelectionMeshScaleX EngineDefinedField <number>
 --- Scale the mesh on the Y axis by this much when we perform our mouse over entity test
----@field SelectionMeshScaleY number
+---@field SelectionMeshScaleY EngineDefinedField <number>
 --- Scale the mesh on the Z axis by this much when we perform our mouse over entity test
----@field SelectionMeshScaleZ number
+---@field SelectionMeshScaleZ EngineDefinedField <number>
 --- Use this much of the top portion of our mesh for intersection test. Useful for naval stuctures
 --- that go deep into water
----@field SelectionMeshUseTopAmount number
+---@field SelectionMeshUseTopAmount EngineDefinedField <number>
 --- x size of the entity's selection box
 ---@field SelectionSizeX number
 --- y size of the entity's selection box
----@field SelectionSizeY number
+---@field SelectionSizeY EngineDefinedField <number>
 --- z size of the entity's selection box
 ---@field SelectionSizeZ number
 --- Use this to modify the thickness of the rendered selection indicator for the unit
@@ -71,12 +71,12 @@
 --- icons were created in and the sort priority of the surrounding icons) 
 ---@field StrategicIconSortPriority integer
 --- Use OOB hit test for this unit when camera is below this zoom level
----@field UseOOBTestZoom number
+---@field UseOOBTestZoom EngineDefinedField <number>
 
 ---@class HitBox
----@field CollisionOffsetX number
----@field CollisionOffsetY number
----@field CollisionOffsetZ number
+---@field CollisionOffsetX EngineDefinedField <number>
+---@field CollisionOffsetY EngineDefinedField <number>
+---@field CollisionOffsetZ EngineDefinedField <number>
 ---@field SizeX number
 ---@field SizeY number
 ---@field SizeZ number

engine/Core/Blueprints/MeshBlueprint.lua

@@ -7,25 +7,25 @@
 --- zoomed out you must be for the icon to appear.
 ---@field IconFadeInZoom number
 --- sort order of mesh we render smallest to largest
----@field SortOrder number
+---@field SortOrder EngineDefinedField <number>
 --- uniform scale factor
----@field UniformScale number
+---@field UniformScale EngineDefinedField<number>
 --- render both above and below the water
----@field StraddleWater boolean
+---@field StraddleWater EngineDefinedField <boolean>
 
 ---@class MeshBlueprintLod
 --- name of mesh to use for this LOD
----@field MeshName FileName
+---@field MeshName EngineDefinedField <FileName>
 --- name of the albedo to use for this LOD
----@field AlbedoName FileName
+---@field AlbedoName EngineDefinedField <FileName>
 --- name of the normal map to use for this LOD
----@field NormalsName FileName
+---@field NormalsName EngineDefinedField <FileName>
 --- name of the specular map to use for this LOD
----@field SpecularName FileName
+---@field SpecularName EngineDefinedField <FileName>
 --- name of the lookup map to use for this LOD
 ---@field LookupName FileName
 --- name of the secondary map to use for this LOD
----@field SecondaryName FileName
+---@field SecondaryName EngineDefinedField <FileName>
 --- the shader name from `Mesh.fx` to use for this LOD
 ---@field ShaderName? string
 --- name of the texture map to use for this LOD