Update CSAR.lua (#1665)

Code formatting and general typo/documentation fixes.

Moose Development/Moose/Ops/CSAR.lua

@@ -42,14 +42,14 @@
 -- # CSAR Concept
 --
 --  * MOOSE-based Helicopter CSAR Operations for Players.
---  * Object oriented refactoring of Ciribob\'s fantastic CSAR script.
+--  * Object oriented refactoring of Ciribob's fantastic CSAR script.
 --  * No need for extra MIST loading.
 --  * Additional events to tailor your mission.
---  * Optional SpawnCASEVAC to create casualties without beacon (e.g. handling dead ground vehicles and create CASVAC requests).
+--  * Optional SpawnCASEVAC to create casualties without beacon (e.g. handling dead ground vehicles and create CASEVAC requests).
 --
 -- ## 0. Prerequisites
 --
--- You need to load an .ogg soundfile for the pilot\'s beacons into the mission, e.g. "beacon.ogg", use a once trigger, "sound to country" for that.
+-- You need to load an .ogg sound file for the pilot's beacons into the mission, e.g. "beacon.ogg", use a once trigger, "sound to country" for that.
 -- Create a late-activated single infantry unit as template in the mission editor and name it e.g. "Downed Pilot".
 --
 -- ## 1. Basic Setup
@@ -68,23 +68,23 @@
 --
 -- The following options are available (with their defaults). Only set the ones you want changed:
 --
---         self.allowDownedPilotCAcontrol = false -- Set to false if you don\'t want to allow control by Combined Arms.
+--         self.allowDownedPilotCAcontrol = false -- Set to false if you don't want to allow control by Combined Arms.
 --         self.allowFARPRescue = true -- allows pilots to be rescued by landing at a FARP or Airbase. Else MASH only!
 --         self.FARPRescueDistance = 1000 -- you need to be this close to a FARP or Airport for the pilot to be rescued.
---         self.autosmoke = false -- automatically smoke a downed pilot\'s location when a heli is near.
+--         self.autosmoke = false -- automatically smoke a downed pilot's location when a helicopter is near.
---         self.autosmokedistance = 1000 -- distance for autosmoke
+--         self.autosmokedistance = 1000 -- distance in meters for automatic smoke deployment
 --         self.coordtype = 1 -- Use Lat/Long DDM (0), Lat/Long DMS (1), MGRS (2), Bullseye imperial (3) or Bullseye metric (4) for coordinates.
 --         self.csarOncrash = false -- (WIP) If set to true, will generate a downed pilot when a plane crashes as well.
 --         self.enableForAI = false -- set to false to disable AI pilots from being rescued.
 --         self.pilotRuntoExtractPoint = true -- Downed pilot will run to the rescue helicopter up to self.extractDistance in meters.
 --         self.extractDistance = 500 -- Distance the downed pilot will start to run to the rescue helicopter.
 --         self.immortalcrew = true -- Set to true to make wounded crew immortal.
---         self.invisiblecrew = false -- Set to true to make wounded crew insvisible.
+--         self.invisiblecrew = false -- Set to true to make wounded crew invisible.
 --         self.loadDistance = 75 -- configure distance for pilots to get into helicopter in meters.
 --         self.mashprefix = {"MASH"} -- prefixes of #GROUP objects used as MASHes.
 --         self.max_units = 6 -- max number of pilots that can be carried if #CSAR.AircraftType is undefined.
 --         self.messageTime = 15 -- Time to show messages for in seconds. Doubled for long messages.
---         self.radioSound = "beacon.ogg" -- the name of the sound file to use for the pilots\' radio beacons. 
+--         self.radioSound = "beacon.ogg" -- the name of the sound file to use for the pilots' radio beacons.
 --         self.smokecolor = 4 -- Color of smoke marker, 0 is green, 1 is red, 2 is white, 3 is orange and 4 is blue.
 --         self.useprefix = true  -- Requires CSAR helicopter #GROUP names to have the prefix(es) defined below.
 --         self.csarPrefix = { "helicargo", "MEDEVAC"} -- #GROUP name prefixes used for useprefix=true - DO NOT use # in helicopter names in the Mission Editor!
@@ -109,10 +109,10 @@
 --
 -- ## 2.1 Experimental Features
 --
---       WARNING - Here\'ll be dragons!
+--       WARNING - Here'll be dragons!
 --       DANGER - For this to work you need to de-sanitize your mission environment (all three entries) in <DCS root>\Scripts\MissionScripting.lua
 --       Needs SRS => 1.9.6 to work (works on the **server** side of SRS)
---       self.useSRS = false -- Set true to use FF\'s SRS integration
+--       self.useSRS = false -- Set true to use FF's SRS integration
 --       self.SRSPath = "E:\\Progra~1\\DCS-SimpleRadio-Standalone\\" -- adjust your own path in your SRS installation -- server(!)
 --       self.SRSchannel = 300 -- radio channel
 --       self.SRSModulation = radio.modulation.AM -- modulation
@@ -141,7 +141,7 @@
 --
 -- ### 4.2. Approach.
 --
---      A CSAR helicpoter is closing in on a downed pilot. Use e.g. `function my_csar:OnAfterApproach(...)` to link into this event:
+--      A CSAR helicopter is closing in on a downed pilot. Use e.g. `function my_csar:OnAfterApproach(...)` to link into this event:
 --
 --          function my_csar:OnAfterApproach(from, event, to, heliname, groupname)
 --            ... your code here ...
@@ -205,7 +205,7 @@ CSAR = {
   hoverStatus = {}, -- tracks status of a helis hover above a downed pilot
   pilotDisabled = {}, -- tracks what aircraft a pilot is disabled for
   pilotLives = {}, -- tracks how many lives a pilot has
-  useprefix    = true,  -- Use the Prefixed defined below, Requires Unit have the Prefix defined below 
+  useprefix = true, -- Use the Prefix defined below, requires Unit to have the Prefix defined
   csarPrefix = {},
   template = nil,
   mash = {},
@@ -344,36 +344,36 @@ function CSAR:New(Coalition, Template, Alias)
   self.rescues = 0 -- counter for successful rescue landings at FARP/AFB/MASH
   self.rescuedpilots = 0 -- counter for saved pilots
   self.csarOncrash = false -- If set to true, will generate a csar when a plane crashes as well.
-  self.allowDownedPilotCAcontrol = false -- Set to false if you don\'t want to allow control by Combined arms.
+  self.allowDownedPilotCAcontrol = false -- Set to false if you don't want to allow control by Combined arms.
   self.enableForAI = false -- set to false to disable AI units from being rescued.
   self.smokecolor = 4 -- Color of smoke marker for blue side, 0 is green, 1 is red, 2 is white, 3 is orange and 4 is blue
   self.coordtype = 2 -- Use Lat/Long DDM (0), Lat/Long DMS (1), MGRS (2), Bullseye imperial (3) or Bullseye metric (4) for coordinates.
   self.immortalcrew = true -- Set to true to make wounded crew immortal
-  self.invisiblecrew = false -- Set to true to make wounded crew insvisible 
+  self.invisiblecrew = false -- Set to true to make wounded crew invisible
   self.messageTime = 15 -- Time to show longer messages for in seconds
-  self.pilotRuntoExtractPoint = true -- Downed Pilot will run to the rescue helicopter up to self.extractDistance METERS 
+  self.pilotRuntoExtractPoint = true -- Downed Pilot will run to the rescue helicopter up to self.extractDistance METERS.
   self.loadDistance = 75 -- configure distance for pilot to get in helicopter in meters.
-  self.extractDistance = 500 -- Distance the Downed pilot will run to the rescue helicopter
+  self.extractDistance = 500 -- Distance the Downed pilot will run to the rescue helicopter.
   self.loadtimemax = 135 -- seconds
-  self.radioSound = "beacon.ogg" -- the name of the sound file to use for the Pilot radio beacons. If this isnt added to the mission BEACONS WONT WORK!
+  self.radioSound = "beacon.ogg" -- the name of the sound file to use for the Pilot radio beacons. If this isn't added to the mission BEACONS WONT WORK!
   self.beaconRefresher = 29 -- seconds
   self.allowFARPRescue = true -- allows pilot to be rescued by landing at a FARP or Airbase
   self.FARPRescueDistance = 1000 -- you need to be this close to a FARP or Airport for the pilot to be rescued.
   self.max_units = 6 -- max number of pilots that can be carried
-  self.useprefix = true  -- Use the Prefixed defined below, Requires Unit have the Prefix defined below 
+  self.useprefix = true -- Use the Prefixed defined below, Requires Unit have the Prefix defined below.
-  self.csarPrefix = { "helicargo", "MEDEVAC"} -- prefixes used for useprefix=true - DON\'T use # in names!
+  self.csarPrefix = { "helicargo", "MEDEVAC" } -- prefixes used for useprefix=true - DON'T use # in names!
   self.template = Template or "generic" -- template for downed pilot
   self.mashprefix = { "MASH" } -- prefixes used to find MASHes
 
   self.autosmoke = false -- automatically smoke location when heli is near
-  self.autosmokedistance = 2000 -- distance for autosmoke
+  self.autosmokedistance = 2000 -- distance in meters for automatic smoke deployment
   -- added 0.1.4
   self.limitmaxdownedpilots = true
   self.maxdownedpilots = 25
   -- generate Frequencies
   self:_GenerateVHFrequencies()
   -- added 0.1.8
-  self.approachdist_far = 5000 -- switch do 10 sec interval approach mode, meters
+  self.approachdist_far = 5000 -- switch to 10 sec interval approach mode, meters
   self.approachdist_near = 3000 -- switch to 5 sec interval approach mode, meters
   self.pilotmustopendoors = false -- switch to true to enable check on open doors
   self.suppressmessages = false
@@ -390,10 +390,10 @@ function CSAR:New(Coalition, Template, Alias)
   -- added 0.1.3
   self.csarUsePara = false -- shagrat set to true, will use the LandingAfterEjection Event instead of Ejection
 
-  -- WARNING - here\'ll be dragons
+  -- WARNING - here'll be dragons
   -- for this to work you need to de-sanitize your mission environment in <DCS root>\Scripts\MissionScripting.lua
   -- needs SRS => 1.9.6 to work (works on the *server* side)
-  self.useSRS = false -- Use FF\'s SRS integration
+  self.useSRS = false -- Use FF's SRS integration
   self.SRSPath = "E:\\Progra~1\\DCS-SimpleRadio-Standalone\\" -- adjust your own path in your server(!)
   self.SRSchannel = 300 -- radio channel
   self.SRSModulation = radio.modulation.AM -- modulation
@@ -446,7 +446,7 @@ function CSAR:New(Coalition, Template, Alias)
   -- @param #string Event Event.
   -- @param #string To To state.
   -- @param #string Heliname Name of the helicopter group.
-  -- @param #string Woundedgroupname Name of the downed pilot\'s group.
+  -- @param #string Woundedgroupname Name of the downed pilot's group.
 
   --- On After "Boarded" event. Downed pilot boarded heli.
   -- @function [parent=#CSAR] OnAfterBoarded
@@ -455,7 +455,7 @@ function CSAR:New(Coalition, Template, Alias)
   -- @param #string Event Event.
   -- @param #string To To state.
   -- @param #string Heliname Name of the helicopter group.
-  -- @param #string Woundedgroupname Name of the downed pilot\'s group.
+  -- @param #string Woundedgroupname Name of the downed pilot's group.
 
   --- On After "Returning" event. Heli can return home with downed pilot(s).
   -- @function [parent=#CSAR] OnAfterReturning
@@ -464,7 +464,7 @@ function CSAR:New(Coalition, Template, Alias)
   -- @param #string Event Event.
   -- @param #string To To state.
   -- @param #string Heliname Name of the helicopter group.
-  -- @param #string Woundedgroupname Name of the downed pilot\'s group.
+  -- @param #string Woundedgroupname Name of the downed pilot's group.
 
   --- On After "Rescued" event. Pilot(s) have been brought to the MASH/FARP/AFB.
   -- @function [parent=#CSAR] OnAfterRescued
@@ -576,7 +576,9 @@ function CSAR:_SpawnPilotInField(country,point,frequency)
   for i = 1, 10 do
     math.random( i, 10000 )
   end
-  if point:IsSurfaceTypeWater() then point.y = 0 end
+  if point:IsSurfaceTypeWater() then
+    point.y = 0
+  end
   local template = self.template
   local alias = string.format( "Pilot %.2fkHz-%d", freq, math.random( 1, 99 ) )
   local coalition = self.coalition
@@ -605,8 +607,8 @@ function CSAR:_AddSpecialOptions(group)
     local _setImmortal = {
       id = 'SetImmortal',
       params = {
-            value = true
+        value = true,
-        }
+      },
     }
     group:SetCommand( _setImmortal )
   end
@@ -615,8 +617,8 @@ function CSAR:_AddSpecialOptions(group)
     local _setInvisible = {
       id = 'SetInvisible',
       params = {
-            value = true
+        value = true,
-        }
+      },
     }
     group:SetCommand( _setInvisible )
   end
@@ -646,7 +648,9 @@ function CSAR:_AddCsar(_coalition , _country, _point, _typeName, _unitName, _pla
 
   if not _freq then
     _freq = self:_GenerateADFFrequency()
-    if not _freq then _freq = 333000 end --noob catch
+    if not _freq then
+      _freq = 333000
+    end -- noob catch
   end
 
   local _spawnedGroup, _alias = self:_SpawnPilotInField( _country, _point, _freq )
@@ -700,7 +704,7 @@ end
 -- @param #number _coalition Coalition.
 -- @param #string _description (optional) Description.
 -- @param #boolean _randomPoint (optional) Random yes or no.
--- @param #boolean _nomessage (optional) If true, don\'t send a message to SAR.
+-- @param #boolean _nomessage (optional) If true, don't send a message to SAR.
 -- @param #string unitname (optional) Name of the lost unit.
 -- @param #string typename (optional) Type of plane.
 -- @param #boolean forcedesc (optional) Force to use the description passed only for the pilot track entry. Use to have fully custom names.
@@ -745,7 +749,7 @@ end
 -- @param #number Coalition Coalition.
 -- @param #string Description (optional) Description.
 -- @param #boolean RandomPoint (optional) Random yes or no.
--- @param #boolean Nomessage (optional) If true, don\'t send a message to SAR.
+-- @param #boolean Nomessage (optional) If true, don't send a message to SAR.
 -- @param #string Unitname (optional) Name of the lost unit.
 -- @param #string Typename (optional) Type of plane.
 -- @param #boolean Forcedesc (optional) Force to use the **description passed only** for the pilot track entry. Use to have fully custom names.
@@ -763,7 +767,7 @@ end
 -- @param #string _Point a POINT_VEC2.
 -- @param #number _coalition Coalition.
 -- @param #string _description (optional) Description.
--- @param #boolean _nomessage (optional) If true, don\'t send a message to SAR.
+-- @param #boolean _nomessage (optional) If true, don't send a message to SAR.
 -- @param #string unitname (optional) Name of the lost unit.
 -- @param #string typename (optional) Type of plane.
 -- @param #boolean forcedesc (optional) Force to use the description passed only for the pilot track entry. Use to have fully custom names.
@@ -797,7 +801,7 @@ end
 -- @param #number Coalition Coalition.
 -- @param #string Description (optional) Description.
 -- @param #boolean addBeacon (optional) yes or no.
--- @param #boolean Nomessage (optional) If true, don\'t send a message to SAR.
+-- @param #boolean Nomessage (optional) If true, don't send a message to SAR.
 -- @param #string Unitname (optional) Name of the lost unit.
 -- @param #string Typename (optional) Type of plane.
 -- @param #boolean Forcedesc (optional) Force to use the **description passed only** for the pilot track entry. Use to have fully custom names.
@@ -1108,7 +1112,7 @@ function CSAR:_CheckWoundedGroupStatus(heliname,woundedgroupname)
 
     if _distance < self.approachdist_near and _distance > 0 then
       if self:_CheckCloseWoundedGroup( _distance, _heliUnit, _heliName, _woundedGroup, _woundedGroupName ) == true then
-        -- we\'re close, reschedule
+        -- we're close, reschedule
         _downedpilot.timestamp = timer.getAbsTime()
         self:__Approach( -5, heliname, woundedgroupname )
       end
@@ -1132,7 +1136,7 @@ function CSAR:_CheckWoundedGroupStatus(heliname,woundedgroupname)
       end
       self.heliCloseMessage[_lookupKeyHeli] = nil
       self.landedStatus[_lookupKeyHeli] = nil
-      --reschedule as units aren\'t dead yet , schedule for a bit slower though as we\'re far away
+      -- reschedule as units aren't dead yet , schedule for a bit slower though as we're far away
       _downedpilot.timestamp = timer.getAbsTime()
       self:__Approach( -10, heliname, woundedgroupname )
     end
@@ -1146,7 +1150,7 @@ function CSAR:_CheckWoundedGroupStatus(heliname,woundedgroupname)
   return self
 end
 
---- (Internal) Function to pop a smoke at a wounded pilot\'s positions.
+--- (Internal) Function to pop a smoke at a wounded pilot's positions.
 -- @param #CSAR self
 -- @param #string _woundedGroupName Name of the group.
 -- @param Wrapper.Group#GROUP _woundedLeader Object of the group.
@@ -1195,14 +1199,7 @@ function CSAR:_PickupUnit(_heliUnit, _pilotName, _woundedGroup, _woundedGroupNam
 
   local found, downedgrouptable = self:_CheckNameInDownedPilots( _woundedGroupName )
   local grouptable = downedgrouptable -- #CSAR.DownedPilot
-  self.inTransitGroups[_heliName][_woundedGroupName] =
+  self.inTransitGroups[_heliName][_woundedGroupName] = { originalUnit = grouptable.originalUnit, woundedGroup = _woundedGroupName, side = self.coalition, desc = grouptable.desc, player = grouptable.player }
-  {
-      originalUnit = grouptable.originalUnit,
-      woundedGroup = _woundedGroupName,
-      side = self.coalition,
-      desc = grouptable.desc,
-      player = grouptable.player,
-  }
 
   _woundedGroup:Destroy( false )
   self:_RemoveNameFromDownedPilots( _woundedGroupName, true )
@@ -1228,7 +1225,6 @@ function CSAR:_OrderGroupToMoveToPoint(_leader, _destination)
   return self
 end
 
-
 --- (internal) Function to check if the heli door(s) are open. Thanks to Shadowze.
 -- @param #CSAR self
 -- @param #string unit_name Name of unit.
@@ -1255,7 +1251,6 @@ function CSAR:_CheckCloseWoundedGroup(_distance, _heliUnit, _heliName, _woundedG
   local _found, _pilotable = self:_CheckNameInDownedPilots( _woundedGroupName ) -- #boolean, #CSAR.DownedPilot
   local _pilotName = _pilotable.desc
 
-  
   local _reset = true
 
   if (_distance < 500) then
@@ -1320,7 +1315,9 @@ function CSAR:_CheckCloseWoundedGroup(_distance, _heliUnit, _heliName, _woundedG
 
           -- check height!
           local leaderheight = _woundedLeader:GetHeight()
-                  if leaderheight < 0 then leaderheight = 0 end
+          if leaderheight < 0 then
+            leaderheight = 0
+          end
           local _height = _heliUnit:GetHeight() - leaderheight
 
           -- TODO - make variable
@@ -1478,7 +1475,7 @@ function CSAR:_DisplayMessageToSAR(_unit, _text, _time, _clear, _speak, _overrid
   return self
 end
 
---- (Internal) Function to get string of a group\'s position.
+--- (Internal) Function to get string of a group's position.
 -- @param #CSAR self
 -- @param Wrapper.Controllable#CONTROLLABLE _woundedGroup Group or Unit object.
 -- @return #string Coordinates as Text
@@ -1608,7 +1605,9 @@ function CSAR:_SignalFlare(_unitName)
 
   local _closest = self:_GetClosestDownedPilot( _heli )
   local smokedist = 8000
-  if self.approachdist_far > smokedist then smokedist = self.approachdist_far end
+  if self.approachdist_far > smokedist then
+    smokedist = self.approachdist_far
+  end
   if _closest ~= nil and _closest.pilot ~= nil and _closest.distance > 0 and _closest.distance < smokedist then
 
     local _clockDir = self:_GetClockDirection( _heli, _closest.pilot )
@@ -1662,7 +1661,9 @@ function CSAR:_Reqsmoke( _unitName )
     return
   end
   local smokedist = 8000
-  if smokedist < self.approachdist_far then smokedist = self.approachdist_far end
+  if smokedist < self.approachdist_far then
+    smokedist = self.approachdist_far
+  end
   local _closest = self:_GetClosestDownedPilot( _heli )
   if _closest ~= nil and _closest.pilot ~= nil and _closest.distance > 0 and _closest.distance < smokedist then
     local _clockDir = self:_GetClockDirection( _heli, _closest.pilot )
@@ -1878,9 +1879,13 @@ function CSAR:_GetClockDirection(_heli, _group)
   local clock = 12
   if _heading then
     local Aspect = Angle - _heading
-    if Aspect == 0 then Aspect = 360 end
+    if Aspect == 0 then
+      Aspect = 360
+    end
     clock = math.abs( UTILS.Round( (Aspect / 30), 0 ) )
-    if clock == 0 then clock = 12 end
+    if clock == 0 then
+      clock = 12
+    end
   end
   return clock
 end
@@ -2037,7 +2042,7 @@ function CSAR:onbeforeStatus(From, Event, To)
         local name = entry.name
         local timestamp = entry.timestamp or 0
         local now = timer.getAbsTime()
-        if now - timestamp > 17 then -- only check if we\'re not in approach mode, which is iterations of 5 and 10.
+        if now - timestamp > 17 then -- only check if we're not in approach mode, which is iterations of 5 and 10.
           self:_CheckWoundedGroupStatus( _sar, name )
         end
       end
@@ -2069,8 +2074,7 @@ function CSAR:onafterStatus(From, Event, To)
   end
 
   if self.verbose > 0 then
-    local text = string.format("%s Active SAR: %d | Downed Pilots in field: %d (max %d) | Pilots boarded: %d | Landings: %d | Pilots rescued: %d",
+    local text = string.format( "%s Active SAR: %d | Downed Pilots in field: %d (max %d) | Pilots boarded: %d | Landings: %d | Pilots rescued: %d", self.lid, NumberOfSARPilots, PilotsInFieldN, self.maxdownedpilots, PilotsBoarded, self.rescues, self.rescuedpilots )
-      self.lid,NumberOfSARPilots,PilotsInFieldN,self.maxdownedpilots,PilotsBoarded,self.rescues,self.rescuedpilots)
     self:T( text )
     if self.verbose < 2 then
       self:I( text )
@@ -2108,7 +2112,7 @@ end
 -- @param #string Event Event triggered.
 -- @param #string To To state.
 -- @param #string Heliname Name of the helicopter group.
--- @param #string Woundedgroupname Name of the downed pilot\'s group.
+-- @param #string Woundedgroupname Name of the downed pilot's group.
 function CSAR:onbeforeApproach( From, Event, To, Heliname, Woundedgroupname )
   self:T( { From, Event, To, Heliname, Woundedgroupname } )
   self:_CheckWoundedGroupStatus( Heliname, Woundedgroupname )
@@ -2121,7 +2125,7 @@ end
 -- @param #string Event Event triggered.
 -- @param #string To To state.
 -- @param #string Heliname Name of the helicopter group.
--- @param #string Woundedgroupname Name of the downed pilot\'s group.
+-- @param #string Woundedgroupname Name of the downed pilot's group.
 function CSAR:onbeforeBoarded( From, Event, To, Heliname, Woundedgroupname )
   self:T( { From, Event, To, Heliname, Woundedgroupname } )
   self:_ScheduledSARFlight( Heliname, Woundedgroupname )
@@ -2134,7 +2138,7 @@ end
 -- @param #string Event Event triggered.
 -- @param #string To To state.
 -- @param #string Heliname Name of the helicopter group.
--- @param #string Woundedgroupname Name of the downed pilot\'s group.
+-- @param #string Woundedgroupname Name of the downed pilot's group.
 -- @param #boolean IsAirport True if heli has landed on an AFB (from event land).
 function CSAR:onbeforeReturning( From, Event, To, Heliname, Woundedgroupname, IsAirPort )
   self:T( { From, Event, To, Heliname, Woundedgroupname } )