From 5f4f565b72accff6bbe74a0e1d885387a3d9b15a Mon Sep 17 00:00:00 2001
From: omltcat <6239696+omltcat@users.noreply.github.com>
Date: Mon, 24 Jun 2024 01:47:56 -0400
Subject: [PATCH] Add Controller.Detection and knowTarget. Add Spot (laser).
 Various minor improvements

---
 library/mission/controller.lua |  8 ++++
 library/mission/spot.lua       | 78 ++++++++++++++++++++++++++++++++++
 library/mission/trigger.lua    |  2 +-
 library/mission/unit.lua       |  2 +-
 library/mission/weapon.lua     |  2 +
 library/mission/world.lua      |  2 +-
 6 files changed, 91 insertions(+), 3 deletions(-)
 create mode 100644 library/mission/spot.lua

diff --git a/library/mission/controller.lua b/library/mission/controller.lua
index 567baf6..2922d0c 100644
--- a/library/mission/controller.lua
+++ b/library/mission/controller.lua
@@ -2,6 +2,7 @@
 
 ---@class Controller
 Controller = {}
+---@enum Controller.Detection
 Controller.Detection = {
     VISUAL  = 1,
     OPTIC   = 2,
@@ -54,3 +55,10 @@ function Controller:setSpeed(speed, keep) end
 ---[Available Tasks](https://wiki.hoggitworld.com/view/DCS_func_setTask)
 ---@param task table -- The task to be set.
 function Controller:setTask(task) end
+
+---Forces the controller to become aware of the specified target, without the controller manually detecting the object itself.<br>
+---Applies only to a Unit Controller. Cannot be used at the group level.
+---@param target Object
+---@param knowType boolean
+---@param knowDistance boolean
+function Controller:knowTarget(target, knowType, knowDistance) end
diff --git a/library/mission/spot.lua b/library/mission/spot.lua
new file mode 100644
index 0000000..55eb2a2
--- /dev/null
+++ b/library/mission/spot.lua
@@ -0,0 +1,78 @@
+---@meta
+---@class Spot
+Spot = {}
+
+---Creates an infrared ray emanating from the given object to a point in 3d space. Can be seen with night vision goggles.<br>
+---localRef is technically an optional variable, however the function's format requires an entry to be made. If not used, simply replace with nil.<br>
+---Example:
+---```
+---local jtac = Unit.getByName('jtacBob')
+---local target = Unit.getByName('BMPAirDefenseSystemGroup1_unit1'):getPoint()
+---local ray = Spot.createInfraRed(jtac, {x = 0, y = 1, z = 0}, target)
+---```
+---@param source Object -- The object from which the infrared ray emanates.
+---@param localRef vec3? -- The local reference point. If not used, replace with nil.
+---@param point vec3 -- The point in 3D space where the infrared ray ends.
+---@return Spot Object
+function Spot.createInfraRed(source, localRef, point) end
+
+---Creates a laser ray emanating from the given object to a point in 3d space.<br>
+---localRef is technically an optional variable, however the function's format requires an entry to be made. If not used, simply replace with nil.<br>
+---If optional variable laserCode is not present the beam will automatically be set to an IR beam. If laserCode is specified, the beam is a laser which can be used to guide laser guided bombs.<br>
+---Laser code is any 4 digit number between 1111 and 1788.<br>
+---Example:
+---```
+---local jtac = Unit.getByName('jtacBob')
+---local target = Unit.getByName('BMPAirDefenseSystemGroup1_unit1'):getPoint()
+---local ray = Spot.createLaser(jtac, {x = 0, y = 1, z = 0}, target, 1337)
+---```
+---@param source Object -- The object from which the laser ray emanates.
+---@param localRef vec3? -- The local reference point. If not used, replace with nil.
+---@param point vec3 -- The point in 3D space where the laser ray ends.
+---@param laseCode integer? -- The laser code for guiding laser guided bombs. Optional.
+---@return Spot Object
+function Spot.createLaser(source, localRef, point, laseCode) end
+
+---Sets the destination point from which the source of the spot is drawn toward.<br>
+---Example:
+---```
+---local jtac = Unit.getByName('jtacBob')
+---local target = Unit.getByName('BMPAirDefenseSystemGroup1_unit1')
+---local ray = Spot.createLaser(jtac, {x = 0, y = 1, z = 0}, target:getPoint(), 1337)
+---local function updateRay()
+---    if Object.isExist(target) then
+---        ray:setPoint(target:getPoint())
+---        timer.scheduleFunction(updateRay, {}, timer.getTime() + 0.5)
+---    else
+---        ray:destroy()
+---    end
+---end
+---timer.scheduleFunction(updateRay, {}, timer.getTime() + 0.5)
+---```
+---@param vec3 table -- The destination point in 3D space.
+function Spot:setPoint(vec3) end
+
+---Returns the laser code used for laser designation tracking.<br>
+---The default and maximum value is 1688.<br>
+---Example:
+---```
+---local jtac = Unit.getByName('jtacBob')
+---local target = Unit.getByName('BMPAirDefenseSystemGroup1_unit1')
+---local ray = Spot.createLaser(jtac, {x = 0, y = 1, z = 0}, target:getPoint(), 1337)
+---local laserCode = ray:getCode()
+---print("Laser code is: " .. laserCode)
+---```
+---@return number
+function Spot:getCode() end
+
+---Sets the laser code for the spot. If no code is provided, a default value is used.<br>
+---Example:
+---```
+---local ray = Spot.createLaser(jtac, {x = 0, y = 1, z = 0}, Unit.getByName('target'):getPoint(), 1337)
+---local function changeCodePlease(code)
+---    local c = code or 1234 -- Default code if none provided
+---    ray:setCode(c)
+---end
+---```
+---@param code number -- The laser code to set. Default and max value is 1688.
+function Spot:setCode(code) end
\ No newline at end of file
diff --git a/library/mission/trigger.lua b/library/mission/trigger.lua
index 5ae612c..9c72b46 100644
--- a/library/mission/trigger.lua
+++ b/library/mission/trigger.lua
@@ -316,7 +316,7 @@ function trigger.misc.getUserFlag(flagNumOrName) end
 
 ---Returns a trigger zone table of a given name.
 ---@param zoneName string -- The name of the trigger zone.
----@return zone -- The trigger zone table. Format: { point = vec3, radius = distance }
+---@return zone? -- The trigger zone table. Format: { point = vec3, radius = distance }
 function trigger.misc.getZone(zoneName) end
 
 ---Sets a user flag to the specified value.
diff --git a/library/mission/unit.lua b/library/mission/unit.lua
index 7ff9d69..921ee57 100644
--- a/library/mission/unit.lua
+++ b/library/mission/unit.lua
@@ -19,7 +19,7 @@ function Unit.getByName(name) end
 
 
 ---Returns an ammo table for all types of loaded ammunition on a given object.
----@return table -- Ammo table is indexed by ammo type and contains a weapon description table and a count variable defining "how many" is on board.
+---@return {count: integer, desc: WeaponDesc}[] -- Ammo table is indexed by ammo type and contains a weapon description table and a count variable defining "how many" is on board.
 function Unit:getAmmo() end
 
 ---Returns a localized string of the unit's callsign.<br>
diff --git a/library/mission/weapon.lua b/library/mission/weapon.lua
index a01a14f..0f13088 100644
--- a/library/mission/weapon.lua
+++ b/library/mission/weapon.lua
@@ -43,6 +43,8 @@ Weapon.WarheadType = {
 ---@class WeaponDesc: ObjectDesc
 ---@field category Weapon.Category
 ---@field warhead WeaponDesc.warhead
+---@field missileCategory Weapon.MissileCategory?
+---@field guidance Weapon.GuidanceType?
 
 ---@class WeaponDesc.warhead
 ---@field explosiveMass number?
diff --git a/library/mission/world.lua b/library/mission/world.lua
index 29be064..bb3127b 100644
--- a/library/mission/world.lua
+++ b/library/mission/world.lua
@@ -106,7 +106,7 @@ world.BirthPlace = {
 ---    myBaseTbl[info.callsign] = info
 ---end
 ---```
----@return table
+---@return Airbase[]
 function world.getAirbases() end
 
 ---Returns a table of mark panels and drawn shapes indexed numerically that are present within the mission.<br>