diff --git a/Moose Development/Moose/Wrapper/Controllable.lua b/Moose Development/Moose/Wrapper/Controllable.lua index 808fb28ec..b81cda295 100644 --- a/Moose Development/Moose/Wrapper/Controllable.lua +++ b/Moose Development/Moose/Wrapper/Controllable.lua @@ -457,12 +457,20 @@ function CONTROLLABLE:CommandSwitchWayPoint( FromWayPoint, ToWayPoint ) return CommandSwitchWayPoint end ---- Perform stop route command +--- Create a stop route command, which returns a string containing the command. +-- Use the result in the method @{#CONTROLLABLE.SetCommand}(). +-- A value of true will make the ground group stop, a value of false will make it continue. +-- Note that this can only work on GROUP level, although individual UNITs can be commanded, the whole GROUP will react. +-- +-- Example missions: +-- +-- * GRP-310 +-- -- @param #CONTROLLABLE self --- @param #boolean StopRoute +-- @param #boolean StopRoute true if the ground unit needs to stop, false if it needs to continue to move. -- @return Dcs.DCSTasking.Task#Task -function CONTROLLABLE:CommandStopRoute( StopRoute, Index ) - self:F2( { StopRoute, Index } ) +function CONTROLLABLE:CommandStopRoute( StopRoute ) + self:F2( { StopRoute } ) local CommandStopRoute = { id = 'StopRoute', @@ -1649,90 +1657,6 @@ function CONTROLLABLE:TaskRouteToZone( Zone, Randomize, Speed, Formation ) return nil end ---- (AIR) Return the Controllable to an @{Airbase#AIRBASE} --- A speed can be given in km/h. --- A given formation can be given. --- @param #CONTROLLABLE self --- @param Wrapper.Airbase#AIRBASE ReturnAirbase The @{Airbase#AIRBASE} to return to. --- @param #number Speed (optional) The speed. --- @return #string The route -function CONTROLLABLE:RouteReturnToAirbase( ReturnAirbase, Speed ) - self:F2( { ReturnAirbase, Speed } ) - --- Example --- [4] = --- { --- ["alt"] = 45, --- ["type"] = "Land", --- ["action"] = "Landing", --- ["alt_type"] = "BARO", --- ["formation_template"] = "", --- ["properties"] = --- { --- ["vnav"] = 1, --- ["scale"] = 0, --- ["angle"] = 0, --- ["vangle"] = 0, --- ["steer"] = 2, --- }, -- end of ["properties"] --- ["ETA"] = 527.81058817743, --- ["airdromeId"] = 12, --- ["y"] = 243127.2973737, --- ["x"] = -5406.2803440839, --- ["name"] = "DictKey_WptName_53", --- ["speed"] = 138.88888888889, --- ["ETA_locked"] = false, --- ["task"] = --- { --- ["id"] = "ComboTask", --- ["params"] = --- { --- ["tasks"] = --- { --- }, -- end of ["tasks"] --- }, -- end of ["params"] --- }, -- end of ["task"] --- ["speed_locked"] = true, --- }, -- end of [4] - - - local DCSControllable = self:GetDCSObject() - - if DCSControllable then - - local ControllablePoint = self:GetVec2() - local ControllableVelocity = self:GetMaxVelocity() - - local PointFrom = {} - PointFrom.x = ControllablePoint.x - PointFrom.y = ControllablePoint.y - PointFrom.type = "Turning Point" - PointFrom.action = "Turning Point" - PointFrom.speed = ControllableVelocity - - - local PointTo = {} - local AirbasePoint = ReturnAirbase:GetVec2() - - PointTo.x = AirbasePoint.x - PointTo.y = AirbasePoint.y - PointTo.type = "Land" - PointTo.action = "Landing" - PointTo.airdromeId = ReturnAirbase:GetID()-- Airdrome ID - self:T(PointTo.airdromeId) - --PointTo.alt = 0 - - local Points = { PointFrom, PointTo } - - self:T3( Points ) - - local Route = { points = Points, } - - return Route - end - - return nil -end -- Commands @@ -1773,6 +1697,8 @@ function CONTROLLABLE:GetTaskRoute() return routines.utils.deepCopy( _DATABASE.Templates.Controllables[self.ControllableName].Template.route.points ) end + + --- Return the route of a controllable by using the @{Database#DATABASE} class. -- @param #CONTROLLABLE self -- @param #number Begin The route point from where the copy will start. The base route point is 0. diff --git a/Moose Development/Moose/Wrapper/Group.lua b/Moose Development/Moose/Wrapper/Group.lua index df263264c..05f11a167 100644 --- a/Moose Development/Moose/Wrapper/Group.lua +++ b/Moose Development/Moose/Wrapper/Group.lua @@ -1,8 +1,6 @@ --- This module contains the GROUP class. -- --- 1) @{Group#GROUP} class, extends @{Controllable#CONTROLLABLE} --- ============================================================= --- The @{Group#GROUP} class is a wrapper class to handle the DCS Group objects: +-- The @{#GROUP} class is a wrapper class to handle the DCS Group objects: -- -- * Support all DCS Group APIs. -- * Enhance with Group specific APIs not in the DCS Group API set. @@ -11,60 +9,8 @@ -- -- **IMPORTANT: ONE SHOULD NEVER SANATIZE these GROUP OBJECT REFERENCES! (make the GROUP object references nil).** -- --- 1.1) GROUP reference methods --- ----------------------- --- For each DCS Group object alive within a running mission, a GROUP wrapper object (instance) will be created within the _@{DATABASE} object. --- This is done at the beginning of the mission (when the mission starts), and dynamically when new DCS Group objects are spawned (using the @{SPAWN} class). --- --- The GROUP class does not contain a :New() method, rather it provides :Find() methods to retrieve the object reference --- using the DCS Group or the DCS GroupName. --- --- Another thing to know is that GROUP objects do not "contain" the DCS Group object. --- The GROUP methods will reference the DCS Group object by name when it is needed during API execution. --- If the DCS Group object does not exist or is nil, the GROUP methods will return nil and log an exception in the DCS.log file. --- --- The GROUP class provides the following functions to retrieve quickly the relevant GROUP instance: --- --- * @{#GROUP.Find}(): Find a GROUP instance from the _DATABASE object using a DCS Group object. --- * @{#GROUP.FindByName}(): Find a GROUP instance from the _DATABASE object using a DCS Group name. --- --- ## 1.2) GROUP task methods --- --- A GROUP is a @{Controllable}. See the @{Controllable} task methods section for a description of the task methods. --- --- ### 1.2.4) Obtain the mission from group templates +-- See the detailed documentation on the GROUP class. -- --- Group templates contain complete mission descriptions. Sometimes you want to copy a complete mission from a group and assign it to another: --- --- * @{Controllable#CONTROLLABLE.TaskMission}: (AIR + GROUND) Return a mission task from a mission template. --- --- ## 1.3) GROUP Command methods --- --- A GROUP is a @{Controllable}. See the @{Controllable} command methods section for a description of the command methods. --- --- ## 1.4) GROUP option methods --- --- A GROUP is a @{Controllable}. See the @{Controllable} option methods section for a description of the option methods. --- --- ## 1.5) GROUP Zone validation methods --- --- The group can be validated whether it is completely, partly or not within a @{Zone}. --- Use the following Zone validation methods on the group: --- --- * @{#GROUP.IsCompletelyInZone}: Returns true if all units of the group are within a @{Zone}. --- * @{#GROUP.IsPartlyInZone}: Returns true if some units of the group are within a @{Zone}. --- * @{#GROUP.IsNotInZone}: Returns true if none of the group units of the group are within a @{Zone}. --- --- The zone can be of any @{Zone} class derived from @{Zone#ZONE_BASE}. So, these methods are polymorphic to the zones tested on. --- --- ## 1.6) GROUP AI methods --- --- A GROUP has AI methods to control the AI activation. --- --- * @{#GROUP.SetAIOnOff}(): Turns the GROUP AI On or Off. --- * @{#GROUP.SetAIOn}(): Turns the GROUP AI On. --- * @{#GROUP.SetAIOff}(): Turns the GROUP AI Off. --- -- ==== -- -- # **API CHANGE HISTORY** @@ -76,6 +22,8 @@ -- -- Hereby the change log: -- +-- 2017-03-26: GROUP:**RouteRTB( RTBAirbase, Speed )** added. +-- -- 2017-03-07: GROUP:**HandleEvent( Event, EventFunction )** added. -- 2017-03-07: GROUP:**UnHandleEvent( Event )** added. -- @@ -100,10 +48,68 @@ -- @module Group -- @author FlightControl ---- The GROUP class --- @type GROUP +--- @type GROUP -- @extends Wrapper.Controllable#CONTROLLABLE -- @field #string GroupName The name of the group. + +--- +-- # GROUP class, extends @{Controllable#CONTROLLABLE} +-- +-- ## GROUP reference methods +-- +-- For each DCS Group object alive within a running mission, a GROUP wrapper object (instance) will be created within the _@{DATABASE} object. +-- This is done at the beginning of the mission (when the mission starts), and dynamically when new DCS Group objects are spawned (using the @{SPAWN} class). +-- +-- The GROUP class does not contain a :New() method, rather it provides :Find() methods to retrieve the object reference +-- using the DCS Group or the DCS GroupName. +-- +-- Another thing to know is that GROUP objects do not "contain" the DCS Group object. +-- The GROUP methods will reference the DCS Group object by name when it is needed during API execution. +-- If the DCS Group object does not exist or is nil, the GROUP methods will return nil and log an exception in the DCS.log file. +-- +-- The GROUP class provides the following functions to retrieve quickly the relevant GROUP instance: +-- +-- * @{#GROUP.Find}(): Find a GROUP instance from the _DATABASE object using a DCS Group object. +-- * @{#GROUP.FindByName}(): Find a GROUP instance from the _DATABASE object using a DCS Group name. +-- +-- ## GROUP task methods +-- +-- A GROUP is a @{Controllable}. See the @{Controllable} task methods section for a description of the task methods. +-- +-- ### Obtain the mission from group templates +-- +-- Group templates contain complete mission descriptions. Sometimes you want to copy a complete mission from a group and assign it to another: +-- +-- * @{Controllable#CONTROLLABLE.TaskMission}: (AIR + GROUND) Return a mission task from a mission template. +-- +-- ## GROUP Command methods +-- +-- A GROUP is a @{Controllable}. See the @{Controllable} command methods section for a description of the command methods. +-- +-- ## GROUP option methods +-- +-- A GROUP is a @{Controllable}. See the @{Controllable} option methods section for a description of the option methods. +-- +-- ## GROUP Zone validation methods +-- +-- The group can be validated whether it is completely, partly or not within a @{Zone}. +-- Use the following Zone validation methods on the group: +-- +-- * @{#GROUP.IsCompletelyInZone}: Returns true if all units of the group are within a @{Zone}. +-- * @{#GROUP.IsPartlyInZone}: Returns true if some units of the group are within a @{Zone}. +-- * @{#GROUP.IsNotInZone}: Returns true if none of the group units of the group are within a @{Zone}. +-- +-- The zone can be of any @{Zone} class derived from @{Zone#ZONE_BASE}. So, these methods are polymorphic to the zones tested on. +-- +-- ## GROUP AI methods +-- +-- A GROUP has AI methods to control the AI activation. +-- +-- * @{#GROUP.SetAIOnOff}(): Turns the GROUP AI On or Off. +-- * @{#GROUP.SetAIOn}(): Turns the GROUP AI On. +-- * @{#GROUP.SetAIOff}(): Turns the GROUP AI Off. +-- +-- @field #GROUP GROUP GROUP = { ClassName = "GROUP", } @@ -895,6 +901,76 @@ function GROUP:InAir() return nil end +do -- Route methods + + --- (AIR) Return the Group to an @{Airbase#AIRBASE}. + -- The following things are to be taken into account: + -- + -- * The group is respawned to achieve the RTB, there may be side artefacts as a result of this. (Like weapons suddenly come back). + -- * A group consisting out of more than one unit, may rejoin formation when respawned. + -- * A speed can be given in km/h. If no speed is specified, the maximum speed of the first unit will be taken to return to base. + -- * When there is no @{Airbase} object specified, the group will return to the home base if the route of the group is pinned at take-off or at landing to a base. + -- * When there is no @{Airbase} object specified and the group route is not pinned to any airbase, it will return to the nearest airbase. + -- + -- @param #GROUP self + -- @param Wrapper.Airbase#AIRBASE RTBAirbase (optional) The @{Airbase} to return to. If blank, the controllable will return to the nearest friendly airbase. + -- @param #number Speed (optional) The Speed, if no Speed is given, the maximum Speed of the first unit is selected. + -- @return #GROUP + function GROUP:RouteRTB( RTBAirbase, Speed ) + self:F2( { RTBAirbase, Speed } ) + + local DCSGroup = self:GetDCSObject() + + if DCSGroup then + + if RTBAirbase then + + local GroupPoint = self:GetVec2() + local GroupVelocity = self:GetUnit(1):GetDesc().speedMax + + local PointFrom = {} + PointFrom.x = GroupPoint.x + PointFrom.y = GroupPoint.y + PointFrom.type = "Turning Point" + PointFrom.action = "Turning Point" + PointFrom.speed = GroupVelocity + + + local PointTo = {} + local AirbasePointVec2 = RTBAirbase:GetPointVec2() + local AirbaseAirPoint = AirbasePointVec2:RoutePointAir( + POINT_VEC3.RoutePointAltType.BARO, + "Land", + "Landing", + Speed or self:GetUnit(1):GetDesc().speedMax + ) + + AirbaseAirPoint["airdromeId"] = RTBAirbase:GetID() + AirbaseAirPoint["speed_locked"] = true, + + self:E(AirbaseAirPoint ) + + local Points = { PointFrom, AirbaseAirPoint } + + self:T3( Points ) + + local Template = self:GetTemplate() + Template.route.points = Points + self:Respawn( Template ) + + self:Route( Points ) + + self:Respawn(Template) + else + self:ClearTasks() + end + end + + return self + end + +end + function GROUP:OnReSpawn( ReSpawnFunction ) self.ReSpawnFunction = ReSpawnFunction diff --git a/Moose Test Missions/GRP - Group Commands/GRP-310 - Command StopRoute/GRP-310 - Command StopRoute.lua b/Moose Test Missions/GRP - Group Commands/GRP-310 - Command StopRoute/GRP-310 - Command StopRoute.lua new file mode 100644 index 000000000..1f7710d18 --- /dev/null +++ b/Moose Test Missions/GRP - Group Commands/GRP-310 - Command StopRoute/GRP-310 - Command StopRoute.lua @@ -0,0 +1,39 @@ +--- +-- Name: GRP-310 - Command StopRoute +-- Author: FlightControl +-- Date Created: 25 Mar 2017 +-- +-- # Situation: +-- A ground unit is moving. +-- Using the command CommandStopMove it will stop moving after 10 seconds. +-- +-- # Test cases: +-- +-- 1. Observe the ground group stopping to move. +-- + +--- @param Wrapper.Group#GROUP GroundGroup +function StopMove( GroundGroup ) + + BASE:E("Stop") + local Command = GroundGroup:CommandStopRoute( true ) + GroundGroup:SetCommand(Command) + +end + +--- @param Wrapper.Group#GROUP GroundGroup +function StartMove( GroundGroup ) + + BASE:E("Start") + local Command = GroundGroup:CommandStopRoute( false ) + GroundGroup:SetCommand(Command) + +end + +GroundGroup = GROUP:FindByName( "Ground" ) + +Scheduler = SCHEDULER:New( nil ) +ScheduleIDStop = Scheduler:Schedule(nil, StopMove, { GroundGroup }, 10, 20 ) +ScheduleIDStart = Scheduler:Schedule(nil, StartMove, { GroundGroup }, 20, 20 ) + + diff --git a/Moose Test Missions/GRP - Group Commands/GRP-310 - Command StopRoute/GRP-310 - Command StopRoute.miz b/Moose Test Missions/GRP - Group Commands/GRP-310 - Command StopRoute/GRP-310 - Command StopRoute.miz new file mode 100644 index 000000000..52b80a623 Binary files /dev/null and b/Moose Test Missions/GRP - Group Commands/GRP-310 - Command StopRoute/GRP-310 - Command StopRoute.miz differ diff --git a/Moose Test Missions/GRP - Group Commands/GRP-400 - RouteReturnToAirbase/GRP-400 - RouteReturnToAirbase.lua b/Moose Test Missions/GRP - Group Commands/GRP-400 - RouteReturnToAirbase/GRP-400 - RouteReturnToAirbase.lua new file mode 100644 index 000000000..47ff792f4 --- /dev/null +++ b/Moose Test Missions/GRP - Group Commands/GRP-400 - RouteReturnToAirbase/GRP-400 - RouteReturnToAirbase.lua @@ -0,0 +1,45 @@ +--- +-- Name: GRP-400 - RouteReturnToAirbase +-- Author: FlightControl +-- Date Created: 25 Mar 2017 +-- +-- # Situation: +-- Three air units are flying and are commanded to return a specific airbase. +-- +-- # Test cases: +-- +-- 1. Observe the Air1 group return to Batumi after 10 seconds. +-- 2. Observe the Air2 group returning to Kobuleti after 300 seconds. (It was planned to land at Kutaisi). +-- 3. Observe the Air3 group returning to the home (landing) airbase after 300 seconds. (It was planned to land at Kutaisi). +-- + +--- @param Wrapper.Group#GROUP AirGroup +function ReturnToBatumi( AirGroup ) + BASE:E("ReturnToBatumi") + AirGroup:RouteRTB( AIRBASE:FindByName("Batumi") ) +end + +--- @param Wrapper.Group#GROUP AirGroup +function ReturnToKobuleti( AirGroup ) + BASE:E("ReturnToKobuleti") + AirGroup:RouteRTB( AIRBASE:FindByName("Kobuleti") ) +end + +--- @param Wrapper.Group#GROUP AirGroup +function ReturnToHome( AirGroup ) + BASE:E("ReturnToHome") + AirGroup:RouteRTB() +end + +Air1Group = GROUP:FindByName( "Air1" ) +Air2Group = GROUP:FindByName( "Air2" ) +Air3Group = GROUP:FindByName( "Air3" ) + +Scheduler = SCHEDULER:New( nil ) +ScheduleIDAir1 = Scheduler:Schedule(nil, ReturnToBatumi, { Air1Group }, 10 ) +ScheduleIDAir2 = Scheduler:Schedule(nil, ReturnToKobuleti, { Air2Group }, 300 ) +ScheduleIDAir3 = Scheduler:Schedule(nil, ReturnToHome, { Air3Group }, 300 ) + + + + diff --git a/Moose Test Missions/GRP - Group Commands/GRP-400 - RouteReturnToAirbase/GRP-400 - RouteReturnToAirbase.miz b/Moose Test Missions/GRP - Group Commands/GRP-400 - RouteReturnToAirbase/GRP-400 - RouteReturnToAirbase.miz new file mode 100644 index 000000000..356b04a2c Binary files /dev/null and b/Moose Test Missions/GRP - Group Commands/GRP-400 - RouteReturnToAirbase/GRP-400 - RouteReturnToAirbase.miz differ diff --git a/docs/Documentation/Controllable.html b/docs/Documentation/Controllable.html index fa850fb75..22bfaf97f 100644 --- a/docs/Documentation/Controllable.html +++ b/docs/Documentation/Controllable.html @@ -246,9 +246,9 @@ This is different from the EnRoute tasks, where the targets of the task need to
Perform stop route command
+Create a stop route command, which returns a string containing the command.
Make the controllable to follow a given route.
-(AIR) Return the Controllable to an Airbase#AIRBASE -A speed can be given in km/h.
Perform stop route command
+Create a stop route command, which returns a string containing the command.
-Use the result in the method CONTROLLABLE.SetCommand(). +A value of true will make the ground group stop, a value of false will make it continue. +Note that this can only work on GROUP level, although individual UNITs can be commanded, the whole GROUP will react.
+ +Example missions:
+ +#boolean StopRoute :
Index :
#boolean StopRoute :
+true if the ground unit needs to stop, false if it needs to continue to move.
(AIR) Return the Controllable to an Airbase#AIRBASE -A speed can be given in km/h.
- - -A given formation can be given.
- -Wrapper.Airbase#AIRBASE ReturnAirbase :
-The Airbase#AIRBASE to return to.
#number Speed :
-(optional) The speed.
#string: -The route
- -The Group#GROUP class is a wrapper class to handle the DCS Group objects:
+The #GROUP class is a wrapper class to handle the DCS Group objects:
IMPORTANT: ONE SHOULD NEVER SANATIZE these GROUP OBJECT REFERENCES! (make the GROUP object references nil).
-For each DCS Group object alive within a running mission, a GROUP wrapper object (instance) will be created within the _DATABASE object. -This is done at the beginning of the mission (when the mission starts), and dynamically when new DCS Group objects are spawned (using the SPAWN class).
- -The GROUP class does not contain a :New() method, rather it provides :Find() methods to retrieve the object reference -using the DCS Group or the DCS GroupName.
- -Another thing to know is that GROUP objects do not "contain" the DCS Group object. -The GROUP methods will reference the DCS Group object by name when it is needed during API execution. -If the DCS Group object does not exist or is nil, the GROUP methods will return nil and log an exception in the DCS.log file.
- -The GROUP class provides the following functions to retrieve quickly the relevant GROUP instance:
- -A GROUP is a Controllable. See the Controllable task methods section for a description of the task methods.
- -Group templates contain complete mission descriptions. Sometimes you want to copy a complete mission from a group and assign it to another:
- -A GROUP is a Controllable. See the Controllable command methods section for a description of the command methods.
- -A GROUP is a Controllable. See the Controllable option methods section for a description of the option methods.
- -The group can be validated whether it is completely, partly or not within a Zone. -Use the following Zone validation methods on the group:
- -The zone can be of any Zone class derived from Zone#ZONE_BASE. So, these methods are polymorphic to the zones tested on.
- -A GROUP has AI methods to control the AI activation.
- -See the detailed documentation on the GROUP class.
Hereby the change log:
+2017-03-26: GROUP:RouteRTB( RTBAirbase, Speed ) added.
+2017-03-07: GROUP:HandleEvent( Event, EventFunction ) added.
2017-03-07: GROUP:UnHandleEvent( Event ) added.
For each DCS Group object alive within a running mission, a GROUP wrapper object (instance) will be created within the _DATABASE object.
Calculate the maxium A2G threat level of the Group.
-Respawn the GROUP using a (tweaked) template of the Group.
+(AIR) Return the Group to an Airbase#AIRBASE.
For each DCS Group object alive within a running mission, a GROUP wrapper object (instance) will be created within the _DATABASE object.
+ + +This is done at the beginning of the mission (when the mission starts), and dynamically when new DCS Group objects are spawned (using the SPAWN class).
+ +The GROUP class does not contain a :New() method, rather it provides :Find() methods to retrieve the object reference +using the DCS Group or the DCS GroupName.
+ +Another thing to know is that GROUP objects do not "contain" the DCS Group object. +The GROUP methods will reference the DCS Group object by name when it is needed during API execution. +If the DCS Group object does not exist or is nil, the GROUP methods will return nil and log an exception in the DCS.log file.
+ +The GROUP class provides the following functions to retrieve quickly the relevant GROUP instance:
+ +A GROUP is a Controllable. See the Controllable task methods section for a description of the task methods.
+ +Group templates contain complete mission descriptions. Sometimes you want to copy a complete mission from a group and assign it to another:
+ +A GROUP is a Controllable. See the Controllable command methods section for a description of the command methods.
+ +A GROUP is a Controllable. See the Controllable option methods section for a description of the option methods.
+ +The group can be validated whether it is completely, partly or not within a Zone. +Use the following Zone validation methods on the group:
+ +The zone can be of any Zone class derived from Zone#ZONE_BASE. So, these methods are polymorphic to the zones tested on.
+ +A GROUP has AI methods to control the AI activation.
+ +GroupGROUPThe GROUP class
- -Calculate the maxium A2G threat level of the Group.
- -(AIR) Return the Group to an Airbase#AIRBASE.
+ + +The following things are to be taken into account:
+ +Wrapper.Airbase#AIRBASE RTBAirbase :
+(optional) The Airbase to return to. If blank, the controllable will return to the nearest friendly airbase.
#number Speed :
+(optional) The Speed, if no Speed is given, the maximum Speed of the first unit is selected.
Contains the counter how many units are currently alive
+Overwrite unit names by default with group name.
-