Update Range.lua

Fix documentation - including typos and updates to no longer correct text.
Remove duplicated RANGE.Defaults.goodthitrange value.
DCS seems to use headings 0-359 (i.e. <360), thus also deduct 360 from an exact 360 heading.

Moose Development/Moose/Functional/Range.lua

@@ -19,7 +19,7 @@
 --   * Bomb, rocket and missile impact points can be marked by smoke.
 --   * Direct hits on targets can trigger flares.
 --   * Smoke and flare colors can be adjusted for each player via radio menu.
---   * Range information and weather report at the range can be reported via radio menu.
+--   * Range information and weather at the range can be obtained via radio menu.
 --   * Persistence: Bombing range results can be saved to disk and loaded the next time the mission is started.
 --   * Range control voice overs (>40) for hit assessment.
 --
@@ -54,7 +54,7 @@
 --- RANGE class
 -- @type RANGE
 -- @field #string ClassName Name of the Class.
--- @field #boolean Debug If true, debug info is send as messages on the screen.
+-- @field #boolean Debug If true, debug info is sent as messages on the screen.
 -- @field #boolean verbose Verbosity level. Higher means more output to DCS log file.
 -- @field #string id String id of range for output in DCS log.
 -- @field #string rangename Name of the range.
@@ -77,13 +77,13 @@
 -- @field #number Tmsg Time [sec] messages to players are displayed. Default 30 sec.
 -- @field #string examinergroupname Name of the examiner group which should get all messages.
 -- @field #boolean examinerexclusive If true, only the examiner gets messages. If false, clients and examiner get messages.
--- @field #number strafemaxalt Maximum altitude above ground for registering for a strafe run. Default is 914 m = 3000 ft.
+-- @field #number strafemaxalt Maximum altitude in meters AGL for registering for a strafe run. Default is 914 m = 3000 ft.
 -- @field #number ndisplayresult Number of (player) results that a displayed. Default is 10.
 -- @field Utilities.Utils#SMOKECOLOR BombSmokeColor Color id used for smoking bomb targets.
 -- @field Utilities.Utils#SMOKECOLOR StrafeSmokeColor Color id used to smoke strafe targets.
 -- @field Utilities.Utils#SMOKECOLOR StrafePitSmokeColor Color id used to smoke strafe pit approach boxes.
--- @field #number illuminationminalt Minimum altitude AGL in meters at which illumination bombs are fired. Default is 500 m.
+-- @field #number illuminationminalt Minimum altitude in meters AGL at which illumination bombs are fired. Default is 500 m.
--- @field #number illuminationmaxalt Maximum altitude AGL in meters at which illumination bombs are fired. Default is 1000 m.
+-- @field #number illuminationmaxalt Maximum altitude in meters AGL at which illumination bombs are fired. Default is 1000 m.
 -- @field #number scorebombdistance Distance from closest target up to which bomb hits are counted. Default 1000 m.
 -- @field #number TdelaySmoke Time delay in seconds between impact of bomb and starting the smoke. Default 3 seconds.
 -- @field #boolean eventmoose If true, events are handled by MOOSE. If false, events are handled directly by DCS eventhandler. Default true.
@@ -131,12 +131,12 @@
 --
 -- A strafe pit can be added to the range by the @{#RANGE.AddStrafePit}(*targetnames, boxlength, boxwidth, heading, inverseheading, goodpass, foulline*) function.
 --
--- * The first parameter *targetnames* defines the target or targets. This has to be given as a lua table which contains the names of @{Wrapper.Unit} or @{Static} objects defined in the mission editor.
+-- * The first parameter *targetnames* defines the target or targets. This can be a single item or a Table with the name(s) of @{Wrapper.Unit} or @{Static} objects defined in the mission editor.
 -- * In order to perform a valid pass on the strafe pit, the pilot has to begin his run from the correct direction. Therefore, an "approach box" is defined in front
---   of the strafe targets. The parameters *boxlength* and *boxwidth* define the size of the box while the parameter *heading* defines its direction.
+--   of the strafe targets. The parameters *boxlength* and *boxwidth* define the size of the box in meters, while the *heading* parameter defines the heading of the box FROM the target.
---   If the parameter *heading* is passed as **nil**, the heading is automatically taken from the heading of the first target unit as defined in the ME.
+--   For example, if heading 120 is set, the approach box will start FROM the target and extend outwards on heading 120. A strafe run approach must then be flown apx. heading 300 TOWARDS the target.
---   The parameter *inverseheading* turns the heading around by 180 degrees. This is sometimes useful, since the default heading of strafe target units point in the
+--   If the parameter *heading* is passed as **nil**, the heading is automatically taken from the heading set in the ME for the first target unit.
---   wrong/opposite direction.
+-- * The parameter *inverseheading* turns the heading around by 180 degrees. This is useful when the default heading of strafe target units point in the wrong/opposite direction.
 -- * The parameter *goodpass* defines the number of hits a pilot has to achieve during a run to be judged as a "good" pass.
 -- * The last parameter *foulline* sets the distance from the pit targets to the foul line. Hit from closer than this line are not counted!
 --
@@ -150,9 +150,8 @@
 --
 -- One ore multiple bombing targets can be added to the range by the @{#RANGE.AddBombingTargets}(targetnames, goodhitrange, randommove) function.
 --
--- * The first parameter *targetnames* has to be a lua table, which contains the names of @{Wrapper.Unit} and/or @{Static} objects defined in the mission editor.
+-- * The first parameter *targetnames* defines the target or targets. This can be a single item or a Table with the name(s) of @{Wrapper.Unit} or @{Static} objects defined in the mission editor.
---   Note that the @{Range} logic **automatically** determines, if a name belongs to a @{Wrapper.Unit} or @{Static} object now.
+-- * The (optional) parameter *goodhitrange* specifies the radius in metres around the target within which a bomb/rocket hit is considered to be "good".
--- * The (optional) parameter *goodhitrange* specifies the radius around the target. If a bomb or rocket falls at a distance smaller than this number, the hit is considered to be "good".
 -- * If final (optional) parameter "*randommove*" can be enabled to create moving targets. If this parameter is set to true, the units of this bombing target will randomly move within the range zone.
 --   Note that there might be quirks since DCS units can get stuck in buildings etc. So it might be safer to manually define a route for the units in the mission editor if moving targets are desired.
 --
@@ -188,7 +187,7 @@
 --
 -- The main range menu can be found at "F10. Other..." --> "F*X*. On the Range..." --> "F1. <Range Name>...".
 --
--- The range menu contains the following submenues:
+-- The range menu contains the following submenus:
 --
 -- ![Banner Image](..\Presentations\RANGE\Menu_Main.png)
 --
@@ -255,9 +254,9 @@
 --      -- Note that this could also be done manually by simply measuring the distance between the target and the foul line in the ME.
 --      GoldwaterRange:GetFoullineDistance("GWR Strafe Pit Left 1", "GWR Foul Line Left")
 --
---      -- Add strafe pits. Each pit (left and right) consists of two targets.
+--      -- Add strafe pits. Each pit (left and right) consists of two targets. Where "nil" is used as input, the default value is used.
---      GoldwaterRange:AddStrafePit(strafepit_left, 3000, 300, nil, true, 20, fouldist)
+--      GoldwaterRange:AddStrafePit(strafepit_left, 3000, 300, nil, true, 30, 500)
---      GoldwaterRange:AddStrafePit(strafepit_right, nil, nil, nil, true, nil, fouldist)
+--      GoldwaterRange:AddStrafePit(strafepit_right, nil, nil, nil, true, nil, 500)
 --
 --      -- Add bombing targets. A good hit is if the bomb falls less then 50 m from the target.
 --      GoldwaterRange:AddBombingTargets(bombtargets, 50)
@@ -349,7 +348,6 @@ RANGE.Defaults={
   boxlength=3000,
   boxwidth=300,
   goodpass=20,
-  goodhitrange=25,
   foulline=610,
 }
 
@@ -833,7 +831,7 @@ end
 
 --- Set maximal strafing altitude. Player entering a strafe pit above that altitude are not registered for a valid pass.
 -- @param #RANGE self
--- @param #number maxalt Maximum altitude AGL in meters. Default is 914 m= 3000 ft.
+-- @param #number maxalt Maximum altitude in meters AGL. Default is 914 m = 3000 ft.
 -- @return #RANGE self
 function RANGE:SetMaxStrafeAlt(maxalt)
   self.strafemaxalt=maxalt or RANGE.Defaults.strafemaxalt
@@ -1022,7 +1020,6 @@ function RANGE:SetMessagesON()
   return self
 end
 
-
 --- Enables tracking of all bomb types. Note that this is the default setting.
 -- @param #RANGE self
 -- @return #RANGE self
@@ -1071,7 +1068,6 @@ function RANGE:TrackMissilesOFF()
   return self
 end
 
-
 --- Enable range control and set frequency.
 -- @param #RANGE self
 -- @param #number frequency Frequency in MHz. Default 256 MHz.
@@ -1105,16 +1101,16 @@ function RANGE:SetSoundfilesPath(path)
 end
 
 --- Add new strafe pit. For a strafe pit, hits from guns are counted. One pit can consist of several units.
--- Note, an approach is only valid, if the player enters via a zone in front of the pit, which defined by boxlength and boxheading.
+-- A strafe run approach is only valid if the player enters via a zone in front of the pit, which is defined by boxlength, boxwidth, and heading.
 -- Furthermore, the player must not be too high and fly in the direction of the pit to make a valid target apporoach.
 -- @param #RANGE self
--- @param #table targetnames Table of unit or static names defining the strafe targets. The first target in the list determines the approach zone (heading and box).
+-- @param #table targetnames Single or multiple (Table) unit or static names defining the strafe targets. The first target in the list determines the approach box origin (heading and box).
 -- @param #number boxlength (Optional) Length of the approach box in meters. Default is 3000 m.
 -- @param #number boxwidth (Optional) Width of the approach box in meters. Default is 300 m.
--- @param #number heading (Optional) Approach heading in Degrees. Default is heading of the unit as defined in the mission editor.
+-- @param #number heading (Optional) Approach box heading in degrees (originating FROM the target). Default is the heading set in the ME for the first target unit
--- @param #boolean inverseheading (Optional) Take inverse heading (heading --> heading - 180 Degrees). Default is false.
+-- @param #boolean inverseheading (Optional) Use inverse heading (heading --> heading - 180 Degrees). Default is false.
 -- @param #number goodpass (Optional) Number of hits for a "good" strafing pass. Default is 20.
--- @param #number foulline (Optional) Foul line distance. Hits from closer than this distance are not counted. Default 610 m = 2000 ft. Set to 0 for no foul line.
+-- @param #number foulline (Optional) Foul line distance. Hits from closer than this distance are not counted. Default is 610 m = 2000 ft. Set to 0 for no foul line.
 -- @return #RANGE self
 function RANGE:AddStrafePit(targetnames, boxlength, boxwidth, heading, inverseheading, goodpass, foulline)
   self:F({targetnames=targetnames, boxlength=boxlength, boxwidth=boxwidth, heading=heading, inverseheading=inverseheading, goodpass=goodpass, foulline=foulline})
@@ -1190,7 +1186,7 @@ function RANGE:AddStrafePit(targetnames, boxlength, boxwidth, heading, inversehe
   if heading < 0 then
     heading=heading+360
   end
-  if heading>360 then
+  if heading >= 360 then
     heading=heading-360
   end
 
@@ -1244,7 +1240,6 @@ function RANGE:AddStrafePit(targetnames, boxlength, boxwidth, heading, inversehe
   return self
 end
 
-
 --- Add all units of a group as one new strafe target pit.
 -- For a strafe pit, hits from guns are counted. One pit can consist of several units.
 -- Note, an approach is only valid, if the player enters via a zone in front of the pit, which defined by boxlength and boxheading.
@@ -1288,7 +1283,7 @@ end
 
 --- Add bombing target(s) to range.
 -- @param #RANGE self
--- @param #table targetnames Table containing names of unit or static objects serving as bomb targets.
+-- @param #table targetnames Single or multiple (Table) names of unit or static objects serving as bomb targets.
 -- @param #number goodhitrange (Optional) Max distance from target unit (in meters) which is considered as a good hit. Default is 25 m.
 -- @param #boolean randommove If true, unit will move randomly within the range. Default is false.
 -- @return #RANGE self
@@ -1382,7 +1377,6 @@ function RANGE:AddBombingTargetUnit(unit, goodhitrange, randommove)
   return self
 end
 
-
 --- Add a coordinate of a bombing target. This
 -- @param #RANGE self
 -- @param Core.Point#COORDINATE coord The coordinate.
@@ -1544,7 +1538,6 @@ function RANGE:onEvent(Event)
 
 end
 
-
 --- Range event handler for event birth.
 -- @param #RANGE self
 -- @param Core.Event#EVENTDATA EventData
@@ -1940,7 +1933,6 @@ function RANGE:onafterStatus(From, Event, To)
       text=text..string.format(", Control %.3f MHz (Relay=%s alive=%s)", self.rangecontrolfreq, tostring(self.rangecontrolrelayname), alive)  
     end
 
-  
     -- Check range status.
     self:I(self.id..text)
 
@@ -1992,7 +1984,6 @@ function RANGE:onafterExitRange(From, Event, To, player)
 
 end
 
-
 --- Function called after bomb impact on range.
 -- @param #RANGE self
 -- @param #string From From state.
@@ -2614,7 +2605,6 @@ function RANGE:_DisplayStrafePits(_unitname)
   end
 end
 
-
 --- Report weather conditions at range. Temperature, QFE pressure and wind data.
 -- @param #RANGE self
 -- @param #string _unitname Name of the player unit.
@@ -2660,7 +2650,6 @@ function RANGE:_DisplayRangeWeather(_unitname)
         tP=string.format("%.2f inHg", P*hPa2inHg)
       end
 
-
       -- Message text.
       text=text..string.format("Weather Report at %s:\n", self.rangename)
       text=text..string.format("--------------------------------------------------\n")
@@ -3056,7 +3045,6 @@ function RANGE:_GetBombTargetCoordinate(target)
   return coord
 end
 
-
 --- Get the number of shells a unit currently has.
 -- @param #RANGE self
 -- @param #string unitname Name of the player unit.
@@ -3582,7 +3570,7 @@ function RANGE:_GetPlayerUnitAndName(_unitName)
   return nil,nil
 end
 
---- Returns a string which consits of this callsign and the player name.
+--- Returns a string which consists of the player name.
 -- @param #RANGE self
 -- @param #string unitname Name of the player unit.
 function RANGE:_myname(unitname)
@@ -3590,9 +3578,11 @@ function RANGE:_myname(unitname)
 
   local unit=UNIT:FindByName(unitname)
   local pname=unit:GetPlayerName()
-  local csign=unit:GetCallsign()
   
+  --TODO: Either remove these leftovers, or implement them.
+  --local csign=unit:GetCallsign()
   --return string.format("%s (%s)", csign, pname)
+  
   return string.format("%s", pname)
 end