General documentation and code fixes (#1650)

Documentation updates for correctness and clarity.
General code formatting updates.
Ajustment to POSITIONABLE:GetCoord to make use of existing POINT:UpdateFromVec3.
Added comments about clarifying the difference between POSITIONABLE:GetCoordinate() and POSITIONABLE:GetCoord() and to perhaps consider a renaming or merging the functions with an optional flag.
This commit is contained in:
TommyC81 2021-12-04 21:50:05 +04:00 committed by GitHub
parent b0818977cf
commit 6360b8c58f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 408 additions and 417 deletions

View File

@ -347,7 +347,6 @@ do -- COORDINATE
return self
end
--- Returns the coordinate from the latitude and longitude given in decimal degrees.
-- @param #COORDINATE self
-- @param #number latitude Latitude in decimal degrees.
@ -372,7 +371,6 @@ do -- COORDINATE
return _coord
end
--- Returns if the 2 coordinates are at the same 2D position.
-- @param #COORDINATE self
-- @param #COORDINATE Coordinate
@ -551,7 +549,7 @@ do -- COORDINATE
-- @param DCS#Distance Distance The Distance to be added in meters.
-- @param DCS#Angle Angle The Angle in degrees. Defaults to 0 if not specified (nil).
-- @param #boolean Keepalt If true, keep altitude of original coordinate. Default is that the new coordinate is created at the translated land height.
-- @param #boolean Overwrite If true, overwrite the original COORDINATE with the translated one. Otherwise, create a new COODINATE.
-- @param #boolean Overwrite If true, overwrite the original COORDINATE with the translated one. Otherwise, create a new COORDINATE.
-- @return #COORDINATE The new calculated COORDINATE.
function COORDINATE:Translate( Distance, Angle, Keepalt, Overwrite )
@ -3004,7 +3002,6 @@ do -- POINT_VEC3
return self
end
--- Create a new POINT_VEC3 object from Vec3 coordinates.
-- @param #POINT_VEC3 self
-- @param DCS#Vec3 Vec3 The Vec3 point.
@ -3017,8 +3014,6 @@ do -- POINT_VEC3
return self
end
--- Return the x coordinate of the POINT_VEC3.
-- @param #POINT_VEC3 self
-- @return #number The x coodinate.

View File

@ -152,7 +152,7 @@
--
-- * 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.
-- * The (optional) parameter *goodhitrange* specifies the radius in metres around the target within which a bomb/rocket 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.
-- * 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.
--
-- ## Adding Groups
@ -903,10 +903,10 @@ end
--- Set player setting whether bomb impact points are smoked or not.
-- @param #RANGE self
-- @param #boolean switch If true nor nil default is to smoke impact points of bombs.
-- @param #boolean switch (Optional) If true, impact points of bombs will be smoked. Default is true.
-- @return #RANGE self
function RANGE:SetDefaultPlayerSmokeBomb(switch)
if switch==true or switch==nil then
if switch == nil or switch == true then
self.defaultsmokebomb=true
else
self.defaultsmokebomb=false
@ -1249,7 +1249,7 @@ end
-- @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 #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.
-- @return #RANGE self
@ -1284,8 +1284,8 @@ end
--- Add bombing target(s) to range.
-- @param #RANGE self
-- @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.
-- @param #number goodhitrange (Optional) Max hit distance from target unit in meters which is considered as a good hit. Default is 25 m.
-- @param #boolean randommove (Optional) If true, unit will move randomly within the range. Default is false.
-- @return #RANGE self
function RANGE:AddBombingTargets(targetnames, goodhitrange, randommove)
self:F({targetnames=targetnames, goodhitrange=goodhitrange, randommove=randommove})
@ -1323,8 +1323,8 @@ end
--- Add a unit or static object as bombing target.
-- @param #RANGE self
-- @param Wrapper.Positionable#POSITIONABLE unit Positionable (unit or static) of the strafe target.
-- @param #number goodhitrange Max distance from unit which is considered as a good hit.
-- @param #boolean randommove If true, unit will move randomly within the range. Default is false.
-- @param #number goodhitrange (Optional) Max hit distance from target unit in meters which is considered as a good hit. Default is 25 m.
-- @param #boolean randommove (Optional) If true, unit will move randomly within the range. Default is false.
-- @return #RANGE self
function RANGE:AddBombingTargetUnit(unit, goodhitrange, randommove)
self:F({unit=unit, goodhitrange=goodhitrange, randommove=randommove})
@ -1339,7 +1339,7 @@ function RANGE:AddBombingTargetUnit(unit, goodhitrange, randommove)
goodhitrange=goodhitrange or RANGE.Defaults.goodhitrange
-- Set randommove to false if it was not specified.
if randommove==nil or _isstatic==true then
if randommove == nil or _isstatic == true then
randommove=false
end
@ -1354,7 +1354,7 @@ function RANGE:AddBombingTargetUnit(unit, goodhitrange, randommove)
-- Get max speed of unit in km/h.
local speed=0
if _isstatic==false then
if _isstatic == false then
speed=self:_GetSpeed(unit)
end
@ -1377,12 +1377,23 @@ function RANGE:AddBombingTargetUnit(unit, goodhitrange, randommove)
return self
end
--- Add a coordinate of a bombing target. This
--- Add a coordinate of a bombing target.
-- @param #RANGE self
-- @param Core.Point#COORDINATE coord The coordinate.
-- @param #string name Name of target.
-- @param #number goodhitrange Max distance from unit which is considered as a good hit.
-- @param #string name (Optional) Name of target. Default is "Bomb Target".
-- @param #number goodhitrange (Optional) Max hit distance from target unit in meters which is considered as a good hit. Default is 25 m.
-- @return #RANGE self
-- @usage
--
-- -- Setup a Range
-- RangeOne = RANGE:New( "Range One" )
-- -- Find the STATIC target object as setup in the ME
-- RangeOneBombTarget = STATIC:FindByName( "RangeOneBombTarget" ):
-- -- Add the coordinate of the STATIC target object as a bomb target (thus keeping the bomb function active, even if the STATIC target is destroyed)
-- RangeOne:AddBombingTargetCoordinate( RangeOneBombTarget:GetCoordinate(), "RangeOneBombTarget", 50)
-- -- Or, add the coordinate of the STATIC target object as a bomb target using default values (name will be "Bomb Target", goodhitrange will be 25 m)
-- RangeOne:AddBombingTargetCoordinate( RangeOneBombTarget:GetCoordinate() )
--
function RANGE:AddBombingTargetCoordinate(coord, name, goodhitrange)
local target={} --#RANGE.BombTarget
@ -1403,8 +1414,8 @@ end
--- Add all units of a group as bombing targets.
-- @param #RANGE self
-- @param Wrapper.Group#GROUP group Group of bombing targets.
-- @param #number goodhitrange Max distance from unit which is considered as a good hit.
-- @param #boolean randommove If true, unit will move randomly within the range. Default is false.
-- @param #number goodhitrange (Optional) Max hit distance from target unit in meters which is considered as a good hit. Default is 25 m.
-- @param #boolean randommove (Optional) If true, unit will move randomly within the range. Default is false.
-- @return #RANGE self
function RANGE:AddBombingTargetGroup(group, goodhitrange, randommove)
self:F({group=group, goodhitrange=goodhitrange, randommove=randommove})
@ -1423,10 +1434,10 @@ function RANGE:AddBombingTargetGroup(group, goodhitrange, randommove)
return self
end
--- Measures the foule line distance between two unit or static objects.
--- Returns the foul line distance between strafe pit target and a foul line distance marker object.
-- @param #RANGE self
-- @param #string namepit Name of the strafe pit target object.
-- @param #string namefoulline Name of the fould line distance marker object.
-- @param #string namefoulline Name of the foul line distance marker object.
-- @return #number Foul line distance in meters.
function RANGE:GetFoullineDistance(namepit, namefoulline)
self:F({namepit=namepit, namefoulline=namefoulline})
@ -1437,7 +1448,7 @@ function RANGE:GetFoullineDistance(namepit, namefoulline)
-- Get the unit or static pit object.
local pit=nil
if _staticpit==true then
if _staticpit == true then
pit=STATIC:FindByName(namepit, false)
elseif _staticpit==false then
pit=UNIT:FindByName(namepit)
@ -1447,9 +1458,9 @@ function RANGE:GetFoullineDistance(namepit, namefoulline)
-- Get the unit or static foul line object.
local foul=nil
if _staticfoul==true then
if _staticfoul == true then
foul=STATIC:FindByName(namefoulline, false)
elseif _staticfoul==false then
elseif _staticfoul == false then
foul=UNIT:FindByName(namefoulline)
else
self:E(self.id..string.format("ERROR! Foul line object %s could not be found in GetFoullineDistance function. Check the name in the ME.", namefoulline))
@ -1457,7 +1468,7 @@ function RANGE:GetFoullineDistance(namepit, namefoulline)
-- Get the distance between the two objects.
local fouldist=0
if pit~=nil and foul~=nil then
if pit ~= nil and foul ~= nil then
fouldist=pit:GetCoordinate():Get2DDistance(foul:GetCoordinate())
else
self:E(self.id..string.format("ERROR! Foul line distance could not be determined. Check pit object name %s and foul line object name %s in the ME.", namepit, namefoulline))
@ -1552,7 +1563,6 @@ function RANGE:OnEventBirth(EventData)
self:T3(self.id.."BIRTH: player = "..tostring(_playername))
if _unit and _playername then
local _uid=_unit:GetID()
local _group=_unit:GetGroup()
local _gid=_group:GetID()
@ -1589,8 +1599,8 @@ function RANGE:OnEventBirth(EventData)
self.timerCheckZone=TIMER:New(self._CheckInZone, self, EventData.IniUnitName):Start(1, 1)
self.planes[_uid] = true
end
end
end
--- Range event handler for event hit.
@ -1607,7 +1617,7 @@ function RANGE:OnEventHit(EventData)
-- Player info
local _unitName = EventData.IniUnitName
local _unit, _playername = self:_GetPlayerUnitAndName(_unitName)
if _unit==nil or _playername==nil then
if _unit == nil or _playername == nil then
return
end
@ -1681,6 +1691,7 @@ function RANGE:OnEventHit(EventData)
end
end
end
end
--- Range event handler for event shot (when a unit releases a rocket or bomb (but not a fast firing gun).
@ -1690,10 +1701,10 @@ function RANGE:OnEventShot(EventData)
self:F({eventshot = EventData})
-- Nil checks.
if EventData.Weapon==nil then
if EventData.Weapon == nil then
return
end
if EventData.IniDCSUnit==nil then
if EventData.IniDCSUnit == nil then
return
end
@ -1741,7 +1752,6 @@ function RANGE:OnEventShot(EventData)
-- Only track if distance player to range is < 25 km. Also check that a player shot. No need to track AI weapons.
if _track and dPR<=self.BombtrackThreshold and _unit and _playername then
-- Player data.
local playerData=self.PlayerSettings[_playername] --#RANGE.PlayerData
@ -2363,7 +2373,7 @@ function RANGE:_DisplayMyBombingResults(_unitName)
end
-- Best 10 runs only.
if i==self.ndisplayresult then
if i == self.ndisplayresult then
break
end
@ -3008,7 +3018,7 @@ end
-- Helper Functions
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------
--- Get the number of shells a unit currently has.
--- Get the coordinate of a Bomb target.
-- @param #RANGE self
-- @param #RANGE.BombTarget target Bomb target data.
-- @return Core.Point#COORDINATE Target coordinate.
@ -3016,7 +3026,7 @@ function RANGE:_GetBombTargetCoordinate(target)
local coord=nil --Core.Point#COORDINATE
if target.type==RANGE.TargetType.UNIT then
if target.type == RANGE.TargetType.UNIT then
if not target.move then
-- Target should not move.
@ -3028,12 +3038,12 @@ function RANGE:_GetBombTargetCoordinate(target)
end
end
elseif target.type==RANGE.TargetType.STATIC then
elseif target.type == RANGE.TargetType.STATIC then
-- Static targets dont move.
coord=target.coordinate
elseif target.type==RANGE.TargetType.COORD then
elseif target.type == RANGE.TargetType.COORD then
-- Coordinates dont move.
coord=target.coordinate

File diff suppressed because it is too large Load Diff

View File

@ -10,11 +10,8 @@
--
-- @module Wrapper.Static
-- @image Wrapper_Static.JPG
--- @type STATIC
-- @extends Wrapper.Positionable#POSITIONABLE
--- Wrapper class to handle Static objects.
--
-- Note that Statics are almost the same as Units, but they don't have a controller.
@ -40,13 +37,10 @@
--
-- * @{#STATIC.FindByName}(): Find a STATIC instance from the _DATABASE object using a DCS Static name.
--
-- IMPORTANT: ONE SHOULD NEVER SANATIZE these STATIC OBJECT REFERENCES! (make the STATIC object references nil).
-- IMPORTANT: ONE SHOULD NEVER SANITIZE these STATIC OBJECT REFERENCES! (make the STATIC object references nil).
--
-- @field #STATIC
STATIC = {
ClassName = "STATIC",
}
STATIC = { ClassName = "STATIC" }
--- Register a static object.
-- @param #STATIC self
@ -58,7 +52,6 @@ function STATIC:Register( StaticName )
return self
end
--- Finds a STATIC from the _DATABASE using a DCSStatic object.
-- @param #STATIC self
-- @param DCS#StaticObject DCSStatic An existing DCS Static object reference.
@ -85,7 +78,7 @@ function STATIC:FindByName( StaticName, RaiseError )
self.StaticName = StaticName
if StaticFound then
return StaticFound
return StaticFound
end
if RaiseError == nil or RaiseError == true then
@ -97,8 +90,9 @@ end
--- Destroys the STATIC.
-- @param #STATIC self
-- @param #boolean GenerateEvent (Optional) true if you want to generate a crash or dead event for the static.
-- @param #boolean GenerateEvent (Optional) true to generate a crash or dead event, false to not generate any event. `nil` (default) creates a remove event.
-- @return #nil The DCS StaticObject is not existing or alive.
--
-- @usage
-- -- Air static example: destroy the static Helicopter and generate a S_EVENT_CRASH.
-- Helicopter = STATIC:FindByName( "Helicopter" )
@ -117,7 +111,7 @@ end
-- @usage
-- -- Destroy without event generation example.
-- Ship = STATIC:FindByName( "Boat" )
-- Ship:Destroy( false ) -- Don't generate an event upon destruction.
-- Ship:Destroy( false ) -- Don't generate any event upon destruction.
--
function STATIC:Destroy( GenerateEvent )
self:F2( self.ObjectName )
@ -148,7 +142,6 @@ function STATIC:Destroy( GenerateEvent )
return nil
end
--- Get DCS object of static of static.
-- @param #STATIC self
-- @return DCS static object
@ -180,7 +173,6 @@ function STATIC:GetUnits()
return nil
end
--- Get threat level of static.
-- @param #STATIC self
-- @return #number Threat level 1.
@ -194,15 +186,15 @@ end
-- @param Core.Point#COORDINATE Coordinate The coordinate where to spawn the new Static.
-- @param #number Heading The heading of the static respawn in degrees. Default is 0 deg.
-- @param #number Delay Delay in seconds before the static is spawned.
function STATIC:SpawnAt(Coordinate, Heading, Delay)
function STATIC:SpawnAt( Coordinate, Heading, Delay )
Heading=Heading or 0
Heading = Heading or 0
if Delay and Delay>0 then
SCHEDULER:New(nil, self.SpawnAt, {self, Coordinate, Heading}, Delay)
if Delay and Delay > 0 then
SCHEDULER:New( nil, self.SpawnAt, { self, Coordinate, Heading }, Delay )
else
local SpawnStatic=SPAWNSTATIC:NewFromStatic(self.StaticName)
local SpawnStatic = SPAWNSTATIC:NewFromStatic( self.StaticName )
SpawnStatic:SpawnFromPointVec2( Coordinate, Heading, self.StaticName )
@ -211,47 +203,43 @@ function STATIC:SpawnAt(Coordinate, Heading, Delay)
return self
end
--- Respawn the @{Wrapper.Unit} at the same location with the same properties.
-- This is useful to respawn a cargo after it has been destroyed.
-- @param #STATIC self
-- @param DCS#country.id CountryID (Optional) The country ID used for spawning the new static. Default is same as currently.
-- @param #number Delay (Optional) Delay in seconds before static is respawned. Default now.
function STATIC:ReSpawn(CountryID, Delay)
function STATIC:ReSpawn( CountryID, Delay )
if Delay and Delay>0 then
SCHEDULER:New(nil, self.ReSpawn, {self, CountryID}, Delay)
if Delay and Delay > 0 then
SCHEDULER:New( nil, self.ReSpawn, { self, CountryID }, Delay )
else
CountryID=CountryID or self:GetCountry()
CountryID = CountryID or self:GetCountry()
local SpawnStatic=SPAWNSTATIC:NewFromStatic(self.StaticName, CountryID)
local SpawnStatic = SPAWNSTATIC:NewFromStatic( self.StaticName, CountryID )
SpawnStatic:Spawn(nil, self.StaticName)
SpawnStatic:Spawn( nil, self.StaticName )
end
return self
end
--- Respawn the @{Wrapper.Unit} at a defined Coordinate with an optional heading.
-- @param #STATIC self
-- @param Core.Point#COORDINATE Coordinate The coordinate where to spawn the new Static.
-- @param #number Heading (Optional) The heading of the static respawn in degrees. Default the current heading.
-- @param #number Delay (Optional) Delay in seconds before static is respawned. Default now.
function STATIC:ReSpawnAt(Coordinate, Heading, Delay)
-- @param #number Heading (Optional) The heading of the static respawn in degrees. Default is the current heading.
-- @param #number Delay (Optional) Delay in seconds before static is respawned. Default is now.
function STATIC:ReSpawnAt( Coordinate, Heading, Delay )
--Heading=Heading or 0
-- Heading=Heading or 0
if Delay and Delay>0 then
SCHEDULER:New(nil, self.ReSpawnAt, {self, Coordinate, Heading}, Delay)
if Delay and Delay > 0 then
SCHEDULER:New( nil, self.ReSpawnAt, { self, Coordinate, Heading }, Delay )
else
local SpawnStatic = SPAWNSTATIC:NewFromStatic( self.StaticName, self:GetCountry() )
local SpawnStatic=SPAWNSTATIC:NewFromStatic(self.StaticName, self:GetCountry())
SpawnStatic:SpawnFromCoordinate(Coordinate, Heading, self.StaticName)
SpawnStatic:SpawnFromCoordinate( Coordinate, Heading, self.StaticName )
end
return self

View File

@ -168,9 +168,6 @@ function UNIT:GetDCSObject()
return nil
end
--- Respawn the @{Wrapper.Unit} using a (tweaked) template of the parent Group.
--
-- This function will:
@ -263,8 +260,6 @@ function UNIT:ReSpawnAt( Coordinate, Heading )
_DATABASE:Spawn( SpawnGroupTemplate )
end
--- Returns if the unit is activated.
-- @param #UNIT self
-- @return #boolean `true` if Unit is activated. `nil` The DCS Unit is not existing or alive.
@ -301,8 +296,6 @@ function UNIT:IsAlive()
return nil
end
--- Returns the Unit's callsign - the localized string.
-- @param #UNIT self
-- @return #string The Callsign of the Unit.
@ -961,7 +954,6 @@ end
-- @return #string Some text.
function UNIT:GetThreatLevel()
local ThreatLevel = 0
local ThreatText = ""
@ -987,7 +979,6 @@ function UNIT:GetThreatLevel()
"LR SAMs"
}
if Attributes["LR SAM"] then ThreatLevel = 10
elseif Attributes["MR SAM"] then ThreatLevel = 9
elseif Attributes["SR SAM"] and
@ -1023,7 +1014,6 @@ function UNIT:GetThreatLevel()
"Fighter"
}
if Attributes["Fighters"] then ThreatLevel = 10
elseif Attributes["Multirole fighters"] then ThreatLevel = 9
elseif Attributes["Battleplanes"] then ThreatLevel = 8
@ -1141,12 +1131,6 @@ function UNIT:OtherUnitInRadius( AwaitUnit, Radius )
return nil
end
--- Returns if the unit is a friendly unit.
-- @param #UNIT self
-- @return #boolean IsFriendly evaluation result.