diff --git a/Moose Development/Moose/Client.lua b/Moose Development/Moose/Client.lua index 75e1ebd16..4326d11cf 100644 --- a/Moose Development/Moose/Client.lua +++ b/Moose Development/Moose/Client.lua @@ -1,10 +1,10 @@ ---- The CLIENT models client units in multi player missions. +--- This module contains the CLIENT class. -- --- @{#CLIENT} class --- ================ +-- 1) @{Client#CLIENT} class, extends @{Unit#UNIT} +-- =============================================== -- Clients are those **Units** defined within the Mission Editor that have the skillset defined as __Client__ or __Player__. -- Note that clients are NOT the same as Units, they are NOT necessarily alive. --- The @{CLIENT} class is a wrapper class to handle the DCS Unit objects that have the skillset defined as __Client__ or __Player__: +-- The @{Client#CLIENT} class is a wrapper class to handle the DCS Unit objects that have the skillset defined as __Client__ or __Player__: -- -- * Wraps the DCS Unit objects with skill level set to Player or Client. -- * Support all DCS Unit APIs. @@ -15,8 +15,8 @@ -- -- Clients are being used by the @{MISSION} class to follow players and register their successes. -- --- CLIENT reference methods --- ======================= +-- 1.1) CLIENT reference methods +-- ----------------------------- -- For each DCS Unit having skill level Player or Client, a CLIENT wrapper object (instance) will be created within the _@{DATABASE} object. -- This is done at the beginning of the mission (when the mission starts). -- diff --git a/Moose Development/Moose/Group.lua b/Moose Development/Moose/Group.lua index faaa6004f..a63d742a5 100644 --- a/Moose Development/Moose/Group.lua +++ b/Moose Development/Moose/Group.lua @@ -1,17 +1,18 @@ ---- GROUP class. --- --- @{GROUP} class --- ============== --- The @{GROUP} class is a wrapper class to handle the DCS Group objects: +--- This module contains the GROUP class. +-- +-- 1) @{Group#GROUP} class, extends @{Base#BASE} +-- ============================================= +-- The @{Group#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. -- * Handle local Group Controller. -- * Manage the "state" of the DCS Group. -- +-- **IMPORTANT: ONE SHOULD NEVER SANATIZE these GROUP OBJECT REFERENCES! (make the GROUP object references nil).** -- --- GROUP reference methods --- ======================= +-- 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). -- @@ -27,7 +28,121 @@ -- * @{#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. -- --- IMPORTANT: ONE SHOULD NEVER SANATIZE these GROUP OBJECT REFERENCES! (make the GROUP object references nil). +-- 1.2) GROUP task methods +-- ----------------------- +-- Several group task methods are available that help you to prepare tasks. +-- These methods return a string consisting of the task description, which can then be given to either a @{Group#GROUP.PushTask} or @{Group#SetTask} method to assign the task to the GROUP. +-- Tasks are specific for the category of the GROUP, more specific, for AIR, GROUND or AIR and GROUND. +-- Each task description where applicable indicates for which group category the task is valid. +-- There are 2 main subdivisions of tasks: Assigned tasks and EnRoute tasks. +-- +-- ### 1.2.1) Assigned task methods +-- +-- Assigned task methods make the group execute the task where the location of the (possible) targets of the task are known before being detected. +-- This is different from the EnRoute tasks, where the targets of the task need to be detected before the task can be executed. +-- +-- Find below a list of the **assigned task** methods: +-- +-- * @{#GROUP.TaskAttackGroup}: (AIR) Attack a Group. +-- * @{#GROUP.TaskAttackMapObject}: (AIR) Attacking the map object (building, structure, e.t.c). +-- * @{#GROUP.TaskAttackUnit}: (AIR) Attack the Unit. +-- * @{#GROUP.TaskBombing}: (AIR) Delivering weapon at the point on the ground. +-- * @{#GROUP.TaskBombingRunway}: (AIR) Delivering weapon on the runway. +-- * @{#GROUP.TaskEmbarking}: (AIR) Move the group to a Vec2 Point, wait for a defined duration and embark a group. +-- * @{#GROUP.TaskEmbarkToTransport}: (GROUND) Embark to a Transport landed at a location. +-- * @{#GROUP.TaskEscort}: (AIR) Escort another airborne group. +-- * @{#GROUP.TaskFAC_AttackGroup}: (AIR + GROUND) The task makes the group/unit a FAC and orders the FAC to control the target (enemy ground group) destruction. +-- * @{#GROUP.TaskFireAtPoint}: (GROUND) Fire at a VEC2 point until ammunition is finished. +-- * @{#GROUP.TaskFollow}: (AIR) Following another airborne group. +-- * @{#GROUP.TaskHold}: (GROUND) Hold ground group from moving. +-- * @{#GROUP.TaskHoldPosition}: (AIR) Hold position at the current position of the first unit of the group. +-- * @{#GROUP.TaskLand}: (AIR HELICOPTER) Landing at the ground. For helicopters only. +-- * @{#GROUP.TaskLandAtZone}: (AIR) Land the group at a @{Zone#ZONE_RADIUS). +-- * @{#GROUP.TaskOrbitCircle}: (AIR) Orbit at the current position of the first unit of the group at a specified alititude. +-- * @{#GROUP.TaskOrbitCircleAtVec2}: (AIR) Orbit at a specified position at a specified alititude during a specified duration with a specified speed. +-- * @{#GROUP.TaskRefueling}: (AIR) Refueling from the nearest tanker. No parameters. +-- * @{#GROUP.TaskRoute}: (AIR + GROUND) Return a Misson task to follow a given route defined by Points. +-- * @{#GROUP.TaskRouteToVec2}: (AIR + GROUND) Make the Group move to a given point. +-- * @{#GROUP.TaskRouteToVec3}: (AIR + GROUND) Make the Group move to a given point. +-- * @{#GROUP.TaskRouteToZone}: (AIR + GROUND) Route the group to a given zone. +-- +-- ### 1.2.2) EnRoute task methods +-- +-- EnRoute tasks require the targets of the task need to be detected by the group (using its sensors) before the task can be executed: +-- +-- * @{#GROUP.EnRouteTaskAWACS}: (AIR) Aircraft will act as an AWACS for friendly units (will provide them with information about contacts). No parameters. +-- * @{#GROUP.EnRouteTaskEngageGroup}: (AIR) Engaging a group. The task does not assign the target group to the unit/group to attack now; it just allows the unit/group to engage the target group as well as other assigned targets. +-- * @{#GROUP.EnRouteTaskEngageTargets}: (AIR) Engaging targets of defined types. +-- * @{#GROUP.EnRouteTaskEWR}: (AIR) Attack the Unit. +-- * @{#GROUP.EnRouteTaskFAC}: (AIR + GROUND) The task makes the group/unit a FAC and lets the FAC to choose a targets (enemy ground group) around as well as other assigned targets. +-- * @{#GROUP.EnRouteTaskFAC_EngageGroup}: (AIR + GROUND) The task makes the group/unit a FAC and lets the FAC to choose the target (enemy ground group) as well as other assigned targets. +-- * @{#GROUP.EnRouteTaskTanker}: (AIR) Aircraft will act as a tanker for friendly units. No parameters. +-- +-- ### 1.2.3) Preparation task methods +-- +-- There are certain task methods that allow to tailor the task behaviour: +-- +-- * @{#GROUP.TaskWrappedAction}: Return a WrappedAction Task taking a Command. +-- * @{#GROUP.TaskCombo}: Return a Combo Task taking an array of Tasks. +-- * @{#GROUP.TaskCondition}: Return a condition section for a controlled task. +-- * @{#GROUP.TaskControlled}: Return a Controlled Task taking a Task and a TaskCondition. +-- +-- ### 1.2.4) 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: +-- +-- * @{#GROUP.TaskMission}: (AIR + GROUND) Return a mission task from a mission template. +-- +-- 1.3) GROUP Command methods +-- -------------------------- +-- Group **command methods** prepare the execution of commands using the @{#GROUP.SetCommand} method: +-- +-- * @{#GROUP.CommandDoScript}: Do Script command. +-- * @{#GROUP.CommandSwitchWayPoint}: Perform a switch waypoint command. +-- +-- 1.4) GROUP Option methods +-- ------------------------- +-- Group **Option methods** change the behaviour of the Group while being alive. +-- +-- ### 1.4.1) Rule of Engagement: +-- +-- * @{#GROUP.OptionROEWeaponFree} +-- * @{#GROUP.OptionROEOpenFire} +-- * @{#GROUP.OptionROEReturnFire} +-- * @{#GROUP.OptionROEEvadeFire} +-- +-- To check whether an ROE option is valid for a specific group, use: +-- +-- * @{#GROUP.OptionROEWeaponFreePossible} +-- * @{#GROUP.OptionROEOpenFirePossible} +-- * @{#GROUP.OptionROEReturnFirePossible} +-- * @{#GROUP.OptionROEEvadeFirePossible} +-- +-- ### 1.4.2) Rule on thread: +-- +-- * @{#GROUP.OptionROTNoReaction} +-- * @{#GROUP.OptionROTPassiveDefense} +-- * @{#GROUP.OptionROTEvadeFire} +-- * @{#GROUP.OptionROTVertical} +-- +-- To test whether an ROT option is valid for a specific group, use: +-- +-- * @{#GROUP.OptionROTNoReactionPossible} +-- * @{#GROUP.OptionROTPassiveDefensePossible} +-- * @{#GROUP.OptionROTEvadeFirePossible} +-- * @{#GROUP.OptionROTVerticalPossible} +-- +-- 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. +-- -- @module Group -- @author FlightControl @@ -524,12 +639,12 @@ end --- Is Functions +-- Is Zone Functions ---- Returns if all units of the group are within a @{Zone#ZONE}. +--- Returns true if all units of the group are within a @{Zone}. -- @param #GROUP self -- @param Zone#ZONE_BASE Zone The zone to test. --- @return #boolean Returns true if the Group is completely within the @{Zone#ZONE} +-- @return #boolean Returns true if the Group is completely within the @{Zone#ZONE_BASE} function GROUP:IsCompletelyInZone( Zone ) self:F2( { self.GroupName, Zone } ) @@ -544,6 +659,40 @@ function GROUP:IsCompletelyInZone( Zone ) return true end +--- Returns true if some units of the group are within a @{Zone}. +-- @param #GROUP self +-- @param Zone#ZONE_BASE Zone The zone to test. +-- @return #boolean Returns true if the Group is completely within the @{Zone#ZONE_BASE} +function GROUP:IsPartlyInZone( Zone ) + self:F2( { self.GroupName, Zone } ) + + for UnitID, UnitData in pairs( self:GetUnits() ) do + local Unit = UnitData -- Unit#UNIT + if Zone:IsPointVec3InZone( Unit:GetPointVec3() ) then + return true + end + end + + return false +end + +--- Returns true if none of the group units of the group are within a @{Zone}. +-- @param #GROUP self +-- @param Zone#ZONE_BASE Zone The zone to test. +-- @return #boolean Returns true if the Group is completely within the @{Zone#ZONE_BASE} +function GROUP:IsNotInZone( Zone ) + self:F2( { self.GroupName, Zone } ) + + for UnitID, UnitData in pairs( self:GetUnits() ) do + local Unit = UnitData -- Unit#UNIT + if Zone:IsPointVec3InZone( Unit:GetPointVec3() ) then + return false + end + end + + return true +end + --- Returns if the group is of an air category. -- If the group is a helicopter or a plane, then this method will return true, otherwise false. -- @param #GROUP self @@ -777,7 +926,7 @@ function GROUP:SetTask( DCSTask, WaitTime ) end ---- Return a condition section for a controlled task +--- Return a condition section for a controlled task. -- @param #GROUP self -- @param DCSTime#Time time -- @param #string userFlag @@ -801,7 +950,7 @@ function GROUP:TaskCondition( time, userFlag, userFlagValue, condition, duration return DCSStopCondition end ---- Return a Controlled Task taking a Task and a TaskCondition +--- Return a Controlled Task taking a Task and a TaskCondition. -- @param #GROUP self -- @param DCSTask#Task DCSTask -- @param #DCSStopCondition DCSStopCondition @@ -823,7 +972,7 @@ function GROUP:TaskControlled( DCSTask, DCSStopCondition ) return DCSTaskControlled end ---- Return a Combo Task taking an array of Tasks +--- Return a Combo Task taking an array of Tasks. -- @param #GROUP self -- @param DCSTask#TaskArray DCSTasks Array of @{DCSTask#Task} -- @return DCSTask#Task @@ -843,7 +992,7 @@ function GROUP:TaskCombo( DCSTasks ) return DCSTaskCombo end ---- Return a WrappedAction Task taking a Command +--- Return a WrappedAction Task taking a Command. -- @param #GROUP self -- @param DCSCommand#Command DCSCommand -- @return DCSTask#Task @@ -1095,7 +1244,7 @@ function GROUP:TaskOrbitCircleAtVec2( Point, Altitude, Speed ) return DCSTask end ---- (AIR) Orbit at the current position of the first unit of the group at a specified alititude +--- (AIR) Orbit at the current position of the first unit of the group at a specified alititude. -- @param #GROUP self -- @param #number Altitude The altitude to hold the position. -- @param #number Speed The speed flying when holding the position. @@ -1271,7 +1420,7 @@ function GROUP:TaskLandAtVec2( Point, Duration ) return DCSTask end ---- (AIR) Land the group at a @{Zone#ZONE). +--- (AIR) Land the group at a @{Zone#ZONE_RADIUS). -- @param #GROUP self -- @param Zone#ZONE Zone The zone where to land. -- @param #number Duration The duration in seconds to stay on the ground. @@ -1292,6 +1441,8 @@ function GROUP:TaskLandAtZone( Zone, Duration, RandomPoint ) return DCSTask end + + --- (AIR) Following another airborne group. -- The unit / group will follow lead unit of another group, wingmens of both groups will continue following their leaders. -- If another group is on land the unit / group will orbit around. @@ -1432,6 +1583,7 @@ function GROUP:TaskHold() return DCSTask end + -- TASKS FOR AIRBORNE AND GROUND UNITS/GROUPS --- (AIR + GROUND) The task makes the group/unit a FAC and orders the FAC to control the target (enemy ground group) destruction. @@ -1504,6 +1656,7 @@ function GROUP:EnRouteTaskEngageTargets( Distance, TargetTypes, Priority ) end + --- (AIR) Engaging a targets of defined types at circle-shaped zone. -- @param #GROUP self -- @param DCSTypes#Vec2 PointVec2 2D-coordinates of the zone. @@ -1538,6 +1691,7 @@ function GROUP:EnRouteTaskEngageTargets( PointVec2, Radius, TargetTypes, Priorit return DCSTask end + --- (AIR) Engaging a group. The task does not assign the target group to the unit/group to attack now; it just allows the unit/group to engage the target group as well as other assigned targets. -- @param #GROUP self -- @param Group#GROUP AttackGroup The Group to be attacked. @@ -1646,6 +1800,7 @@ function GROUP:EnRouteTaskEngageUnit( AttackUnit, Priority, WeaponType, WeaponEx end + --- (AIR) Aircraft will act as an AWACS for friendly units (will provide them with information about contacts). No parameters. -- @param #GROUP self -- @return DCSTask#Task The DCS task structure. @@ -1792,13 +1947,13 @@ end ---- Move the group to a Vec2 Point, wait for a defined duration and embark a group. +--- (AIR) Move the group to a Vec2 Point, wait for a defined duration and embark a group. -- @param #GROUP self -- @param DCSTypes#Vec2 Point The point where to wait. -- @param #number Duration The duration in seconds to wait. -- @param #GROUP EmbarkingGroup The group to be embarked. -- @return DCSTask#Task The DCS task structure -function GROUP:TaskEmbarkingAtVec2( Point, Duration, EmbarkingGroup ) +function GROUP:TaskEmbarking( Point, Duration, EmbarkingGroup ) self:F2( { self.GroupName, Point, Duration, EmbarkingGroup.DCSGroup } ) local DCSTask @@ -1817,12 +1972,14 @@ function GROUP:TaskEmbarkingAtVec2( Point, Duration, EmbarkingGroup ) return DCSTask end +--- (GROUND) Embark to a Transport landed at a location. + --- Move to a defined Vec2 Point, and embark to a group when arrived within a defined Radius. -- @param #GROUP self -- @param DCSTypes#Vec2 Point The point where to wait. -- @param #number Radius The radius of the embarking zone around the Point. -- @return DCSTask#Task The DCS task structure. -function GROUP:TaskEmbarkToTransportAtVec2( Point, Radius ) +function GROUP:TaskEmbarkToTransport( Point, Radius ) self:F2( { self.GroupName, Point, Radius } ) local DCSTask --DCSTask#Task @@ -1837,7 +1994,9 @@ function GROUP:TaskEmbarkToTransportAtVec2( Point, Radius ) return DCSTask end ---- Return a Misson task from a mission template. + + +--- (AIR + GROUND) Return a mission task from a mission template. -- @param #GROUP self -- @param #table TaskMission A table containing the mission task. -- @return DCSTask#Task @@ -1865,7 +2024,7 @@ function GROUP:TaskRoute( Points ) return DCSTask end ---- Make the DCS Group to fly to a given point and hover. +--- (AIR + GROUND) Make the Group move to fly to a given point. -- @param #GROUP self -- @param DCSTypes#Vec3 Point The destination point in Vec3 format. -- @param #number Speed The speed to travel. @@ -1916,7 +2075,7 @@ function GROUP:TaskRouteToVec2( Point, Speed ) return self end ---- Make the DCS Group to fly to a given point and hover. +--- (AIR + GROUND) Make the Group move to a given point. -- @param #GROUP self -- @param DCSTypes#Vec3 Point The destination point in Vec3 format. -- @param #number Speed The speed to travel. @@ -1997,7 +2156,7 @@ end ---- Route the group to a given zone. +--- (AIR + GROUND) Route the group to a given zone. -- The group final destination point can be randomized. -- A speed can be given in km/h. -- A given formation can be given. diff --git a/Moose Development/Moose/Unit.lua b/Moose Development/Moose/Unit.lua index 5df82eeec..a4da510e2 100644 --- a/Moose Development/Moose/Unit.lua +++ b/Moose Development/Moose/Unit.lua @@ -1,8 +1,8 @@ ---- UNIT Class +--- This module contains the UNIT class. -- --- @{UNIT} class --- ============== --- The @{UNIT} class is a wrapper class to handle the DCS Unit objects: +-- 1) @{Unit#UNIT} class, extends @{Base#BASE} +-- =========================================== +-- The @{Unit#UNIT} class is a wrapper class to handle the DCS Unit objects: -- -- * Support all DCS Unit APIs. -- * Enhance with Unit specific APIs not in the DCS Unit API set. @@ -10,8 +10,8 @@ -- * Manage the "state" of the DCS Unit. -- -- --- UNIT reference methods --- ====================== +-- 1.1) UNIT reference methods +-- ---------------------- -- For each DCS Unit object alive within a running mission, a UNIT 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 Unit objects are spawned (using the @{SPAWN} class). -- @@ -29,19 +29,15 @@ -- -- IMPORTANT: ONE SHOULD NEVER SANATIZE these UNIT OBJECT REFERENCES! (make the UNIT object references nil). -- --- DCS UNIT APIs --- ============= +-- 1.2) DCS UNIT APIs +-- ------------------ -- The DCS Unit APIs are used extensively within MOOSE. The UNIT class has for each DCS Unit API a corresponding method. -- To be able to distinguish easily in your code the difference between a UNIT API call and a DCS Unit API call, -- the first letter of the method is also capitalized. So, by example, the DCS Unit method @{DCSUnit#Unit.getName}() -- is implemented in the UNIT class as @{#UNIT.GetName}(). -- --- Additional UNIT APIs --- ==================== --- The UNIT class comes with additional methods. Find below a summary. --- --- Smoke, Flare Units --- ------------------ +-- 1.3) Smoke, Flare Units +-- ----------------------- -- The UNIT class provides methods to smoke or flare units easily. -- The @{#UNIT.SmokeBlue}(), @{#UNIT.SmokeGreen}(),@{#UNIT.SmokeOrange}(), @{#UNIT.SmokeRed}(), @{#UNIT.SmokeRed}() methods -- will smoke the unit in the corresponding color. Note that smoking a unit is done at the current position of the DCS Unit. @@ -49,26 +45,25 @@ -- The @{#UNIT.FlareGreen}(), @{#UNIT.FlareRed}(), @{#UNIT.FlareWhite}(), @{#UNIT.FlareYellow}() -- methods will fire off a flare in the air with the corresponding color. Note that a flare is a one-off shot and its effect is of very short duration. -- --- Position, Point --- --------------- +-- 1.4) Location Position, Point +-- ----------------------------- -- The UNIT class provides methods to obtain the current point or position of the DCS Unit. --- The @{#UNIT.GetPointVec2}(), @{#UNIT.GetPointVec3}() will obtain the current location of the DCS Unit in a Vec2 (2D) or a Vec3 (3D) vector respectively. --- If you want to obtain the complete 3D position including oriëntation and direction vectors, consult the @{#UNIT.GetPositionVec3}() method respectively. +-- The @{#UNIT.GetPointVec2}(), @{#UNIT.GetPointVec3}() will obtain the current **location** of the DCS Unit in a Vec2 (2D) or a **point** in a Vec3 (3D) vector respectively. +-- If you want to obtain the complete **3D position** including oriëntation and direction vectors, consult the @{#UNIT.GetPositionVec3}() method respectively. -- --- Alive --- ----- +-- 1.5) Test if alive +-- ------------------ -- The @{#UNIT.IsAlive}(), @{#UNIT.IsActive}() methods determines if the DCS Unit is alive, meaning, it is existing and active. -- --- Test for other units in radius --- ------------------------------ --- One can test if another DCS Unit is within a given radius of the current DCS Unit, by using the @{#UNIT.OtherUnitInRadius}() method. --- --- More functions will be added --- ---------------------------- --- During the MOOSE development, more functions will be added. A complete list of the current functions is below. --- +-- 1.6) Test for proximity +-- ----------------------- +-- The UNIT class contains methods to test the location or proximity against zones or other objects. -- +-- ### 1.6.1) Zones +-- To test whether the Unit is within a **zone**, use the @{#UNIT.IsInZone}() or the @{#UNIT.IsNotInZone}() methods. Any zone can be tested on, but the zone must be derived from @{Zone#ZONE_BASE}. -- +-- ### 1.6.2) Units +-- Test if another DCS Unit is within a given radius of the current DCS Unit, use the @{#UNIT.OtherUnitInRadius}() method. -- -- @module Unit -- @author FlightControl @@ -601,7 +596,35 @@ function UNIT:GetVelocity() return nil end - + +-- Is functions + +--- Returns true if the unit is within a @{Zone}. +-- @param #UNIT self +-- @param Zone#ZONE_BASE Zone The zone to test. +-- @return #boolean Returns true if the unit is within the @{Zone#ZONE_BASE} +function UNIT:IsInZone( Zone ) + self:F2( { self.UnitName, Zone } ) + + local IsInZone = Zone:IsPointVec3InZone( self:GetPointVec3() ) + + self:T( { IsInZone } ) + return IsInZone +end + +--- Returns true if the unit is not within a @{Zone}. +-- @param #UNIT self +-- @param Zone#ZONE_BASE Zone The zone to test. +-- @return #boolean Returns true if the unit is not within the @{Zone#ZONE_BASE} +function UNIT:IsNotInZone( Zone ) + self:F2( { self.UnitName, Zone } ) + + local IsInZone = not Zone:IsPointVec3InZone( self:GetPointVec3() ) + + self:T( { IsInZone } ) + return IsInZone +end + --- Returns true if the DCS Unit is in the air. -- @param Unit#UNIT self -- @return #boolean true if in the air. diff --git a/Moose Development/Moose/Zone.lua b/Moose Development/Moose/Zone.lua index 2d061e1a2..feeba12f7 100644 --- a/Moose Development/Moose/Zone.lua +++ b/Moose Development/Moose/Zone.lua @@ -1,6 +1,4 @@ ---- ZONE Classes --- ============= --- This module contains the ZONE classes, inherited from @{Zone#ZONE_BASE}. +--- This module contains the ZONE classes, inherited from @{Zone#ZONE_BASE}. -- There are essentially two core functions that zones accomodate: -- -- * Test if an object is within the zone boundaries. @@ -23,12 +21,30 @@ -- * @{Zone#ZONE_UNIT}: The ZONE_UNIT class defined by a zone around a @{Unit#UNIT} with a radius. -- * @{Zone#ZONE_POLYGON}: The ZONE_POLYGON class defined by a sequence of @{Group#GROUP} waypoints within the Mission Editor, forming a polygon. -- --- Polymorphic methods --- =================== -- Each zone implements two polymorphic functions defined in @{Zone#ZONE_BASE}: -- --- * @{#ZONE_BASE.IsPointVec2InZone}: Returns if a location is within the zone. --- * @{#ZONE_BASE.IsPointVec3InZone}: Returns if a point is within the zone. +-- * @{#ZONE_BASE.IsPointVec2InZone}: Returns if a location is within the zone. +-- * @{#ZONE_BASE.IsPointVec3InZone}: Returns if a point is within the zone. +-- +-- 1) @{Zone#ZONE_BASE} class, extends @{Base#BASE} +-- ================================================ +-- The ZONE_BASE class defining the base for all other zone classes. +-- +-- 2) @{Zone#ZONE_RADIUS} class, extends @{Zone#ZONE_BASE} +-- ======================================================= +-- The ZONE_RADIUS class defined by a zone name, a location and a radius. +-- +-- 3) @{Zone#ZONE} class, extends @{Zone#ZONE_RADIUS} +-- ========================================== +-- The ZONE class, defined by the zone name as defined within the Mission Editor. +-- +-- 4) @{Zone#ZONE_UNIT} class, extends @{Zone#ZONE_RADIUS} +-- ======================================================= +-- The ZONE_UNIT class defined by a zone around a @{Unit#UNIT} with a radius. +-- +-- 5) @{Zone#ZONE_POLYGON} class, extends @{Zone#ZONE_BASE} +-- ======================================================== +-- The ZONE_POLYGON class defined by a sequence of @{Group#GROUP} waypoints within the Mission Editor, forming a polygon. -- -- @module Zone -- @author FlightControl diff --git a/Moose Training/Documentation/Client.html b/Moose Training/Documentation/Client.html index 25c6e929e..3ac967009 100644 --- a/Moose Training/Documentation/Client.html +++ b/Moose Training/Documentation/Client.html @@ -71,14 +71,14 @@

Module Client

-

The CLIENT models client units in multi player missions.

+

This module contains the CLIENT class.

-

#CLIENT class

+

1) Client#CLIENT class, extends Unit#UNIT

Clients are those Units defined within the Mission Editor that have the skillset defined as Client or Player. Note that clients are NOT the same as Units, they are NOT necessarily alive. -The CLIENT class is a wrapper class to handle the DCS Unit objects that have the skillset defined as Client or Player:

+The Client#CLIENT class is a wrapper class to handle the DCS Unit objects that have the skillset defined as Client or Player:

-

IMPORTANT: ONE SHOULD NEVER SANATIZE these GROUP OBJECT REFERENCES! (make the GROUP object references nil).

+

1.2) GROUP task methods

+

Several group task methods are available that help you to prepare tasks. +These methods return a string consisting of the task description, which can then be given to either a Group#GROUP.PushTask or Group#SetTask method to assign the task to the GROUP. +Tasks are specific for the category of the GROUP, more specific, for AIR, GROUND or AIR and GROUND. +Each task description where applicable indicates for which group category the task is valid. +There are 2 main subdivisions of tasks: Assigned tasks and EnRoute tasks.

+ +

1.2.1) Assigned task methods

+ +

Assigned task methods make the group execute the task where the location of the (possible) targets of the task are known before being detected. +This is different from the EnRoute tasks, where the targets of the task need to be detected before the task can be executed.

+ +

Find below a list of the assigned task methods:

+ + + +

1.2.2) EnRoute task methods

+ +

EnRoute tasks require the targets of the task need to be detected by the group (using its sensors) before the task can be executed:

+ + + +

1.2.3) Preparation task methods

+ +

There are certain task methods that allow to tailor the task behaviour:

+ + + +

1.2.4) 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:

+ + + +

1.3) GROUP Command methods

+

Group command methods prepare the execution of commands using the GROUP.SetCommand method:

+ + + +

1.4) GROUP Option methods

+

Group Option methods change the behaviour of the Group while being alive.

+ +

1.4.1) Rule of Engagement:

+ + + +

To check whether an ROE option is valid for a specific group, use:

+ + + +

1.4.2) Rule on thread:

+ + + +

To test whether an ROT option is valid for a specific group, use:

+ + + +

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:

+ + + +

The zone can be of any Zone class derived from Zone#ZONE_BASE. So, these methods are polymorphic to the zones tested on.

+

Global(s)

@@ -409,6 +539,12 @@ If the DCS Group object does not exist or is nil, the GROUP methods will return + + + + @@ -421,6 +557,18 @@ If the DCS Group object does not exist or is nil, the GROUP methods will return + + + + + + + + @@ -630,31 +778,31 @@ If the DCS Group object does not exist or is nil, the GROUP methods will return - + - + @@ -708,19 +856,19 @@ If the DCS Group object does not exist or is nil, the GROUP methods will return @@ -744,25 +892,25 @@ If the DCS Group object does not exist or is nil, the GROUP methods will return @@ -843,8 +991,6 @@ If the DCS Group object does not exist or is nil, the GROUP methods will return

Type DCSStopCondition

-

Type Duration

-

Type GROUP

The GROUP class

@@ -1984,6 +2130,33 @@ true if the DCS Group is alive.

+ +GROUP:IsCompletelyInZone(Zone) + +
+
+ +

Returns true if all units of the group are within a Zone.

+ +

Parameter

+ +

Return value

+ +

#boolean: +Returns true if the Group is completely within the Zone#ZONE_BASE

+ +
+
+
+
+ GROUP:IsGround() @@ -2020,6 +2193,60 @@ true if DCS Group contains Helicopters.

+ +GROUP:IsNotInZone(Zone) + +
+
+ +

Returns true if none of the group units of the group are within a Zone.

+ +

Parameter

+ +

Return value

+ +

#boolean: +Returns true if the Group is completely within the Zone#ZONE_BASE

+ +
+
+
+
+ + +GROUP:IsPartlyInZone(Zone) + +
+
+ +

Returns true if some units of the group are within a Zone.

+ +

Parameter

+ +

Return value

+ +

#boolean: +Returns true if the Group is completely within the Zone#ZONE_BASE

+ +
+
+
+
+ GROUP:IsShip() @@ -2077,7 +2304,7 @@ The message text

  • -

    #Duration Duration : +

    DCSTypes#Duration Duration : The duration of the message.

    • @@ -2113,7 +2340,7 @@ The message text

  • -

    #Duration Duration : +

    DCSTypes#Duration Duration : The duration of the message.

    • @@ -2144,7 +2371,7 @@ The message text

  • -

    #Duration Duration : +

    DCSTypes#Duration Duration : The duration of the message.

    • @@ -2175,7 +2402,7 @@ The message text

  • -

    #Duration Duration : +

    DCSTypes#Duration Duration : The duration of the message.

    • @@ -2212,7 +2439,7 @@ The message text

  • -

    #Duration Duration : +

    DCSTYpes#Duration Duration : The duration of the message.

    • @@ -2973,7 +3200,7 @@ The DCS task structure.

    -

    Return a Combo Task taking an array of Tasks

    +

    Return a Combo Task taking an array of Tasks.

    Parameter

    -

    Return a condition section for a controlled task

    +

    Return a condition section for a controlled task.

    Parameters

      @@ -3047,7 +3274,7 @@ return DCSTask#Task

      -

      Return a Controlled Task taking a Task and a TaskCondition

      +

      Return a Controlled Task taking a Task and a TaskCondition.

      Parameters

        @@ -3072,8 +3299,8 @@ return DCSTask#Task

        - -GROUP:TaskEmbarkToTransportAtVec2(Point, Radius) + +GROUP:TaskEmbarkToTransport(Point, Radius)
        @@ -3105,13 +3332,13 @@ The DCS task structure.

        - -GROUP:TaskEmbarkingAtVec2(Point, Duration, EmbarkingGroup) + +GROUP:TaskEmbarking(Point, Duration, EmbarkingGroup)
        -

        Move the group to a Vec2 Point, wait for a defined duration and embark a group.

        +

        (AIR) Move the group to a Vec2 Point, wait for a defined duration and embark a group.

        Parameters

          @@ -3457,7 +3684,7 @@ self

          -

          (AIR) Land the group at a @{Zone#ZONE).

          +

          (AIR) Land the group at a @{Zone#ZONE_RADIUS).

          Parameters

            @@ -3495,7 +3722,7 @@ self

            -

            Return a Misson task from a mission template.

            +

            (AIR + GROUND) Return a mission task from a mission template.

            Parameter

              @@ -3522,7 +3749,7 @@ A table containing the mission task.

              -

              (AIR) Orbit at the current position of the first unit of the group at a specified alititude

              +

              (AIR) Orbit at the current position of the first unit of the group at a specified alititude.

              Parameters

                @@ -3642,7 +3869,7 @@ A table of route points.

                -

                Make the DCS Group to fly to a given point and hover.

                +

                (AIR + GROUND) Make the Group move to fly to a given point.

                Parameters

                  @@ -3675,7 +3902,7 @@ self

                  -

                  Make the DCS Group to fly to a given point and hover.

                  +

                  (AIR + GROUND) Make the Group move to a given point.

                  Parameters

                    @@ -3708,7 +3935,7 @@ self

                    -

                    Route the group to a given zone.

                    +

                    (AIR + GROUND) Route the group to a given zone.

                    The group final destination point can be randomized. @@ -3753,7 +3980,7 @@ The formation string.

                    -

                    Return a WrappedAction Task taking a Command

                    +

                    Return a WrappedAction Task taking a Command.

                    Parameters

                      diff --git a/Moose Training/Documentation/Unit.html b/Moose Training/Documentation/Unit.html index 3d7fab51f..a4f339517 100644 --- a/Moose Training/Documentation/Unit.html +++ b/Moose Training/Documentation/Unit.html @@ -71,24 +71,22 @@

                      Module Unit

                      -

                      UNIT Class

                      +

                      This module contains the UNIT class.

                      -

                      UNIT class

                      -

                      The UNIT class is a wrapper class to handle the DCS Unit objects:

                      + + +

                      1) Unit#UNIT class, extends Base#BASE

                      +

                      The Unit#UNIT class is a wrapper class to handle the DCS Unit objects:

                      • Support all DCS Unit APIs.
                        • -
                      - - -
                      • Enhance with Unit specific APIs not in the DCS Unit API set.
                      • Handle local Unit Controller.
                      • Manage the "state" of the DCS Unit.
                      -

                      UNIT reference methods

                      +

                      1.1) UNIT reference methods

                      For each DCS Unit object alive within a running mission, a UNIT 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 Unit objects are spawned (using the SPAWN class).

                      @@ -108,16 +106,13 @@ If the DCS Unit object does not exist or is nil, the UNIT methods will return ni

                      IMPORTANT: ONE SHOULD NEVER SANATIZE these UNIT OBJECT REFERENCES! (make the UNIT object references nil).

                      -

                      DCS UNIT APIs

                      +

                      1.2) DCS UNIT APIs

                      The DCS Unit APIs are used extensively within MOOSE. The UNIT class has for each DCS Unit API a corresponding method. To be able to distinguish easily in your code the difference between a UNIT API call and a DCS Unit API call, the first letter of the method is also capitalized. So, by example, the DCS Unit method DCSUnit#Unit.getName() is implemented in the UNIT class as UNIT.GetName().

                      -

                      Additional UNIT APIs

                      -

                      The UNIT class comes with additional methods. Find below a summary.

                      - -

                      Smoke, Flare Units

                      +

                      1.3) Smoke, Flare Units

                      The UNIT class provides methods to smoke or flare units easily. The UNIT.SmokeBlue(), UNIT.SmokeGreen(),UNIT.SmokeOrange(), UNIT.SmokeRed(), UNIT.SmokeRed() methods will smoke the unit in the corresponding color. Note that smoking a unit is done at the current position of the DCS Unit. @@ -125,22 +120,22 @@ When the DCS Unit moves for whatever reason, the smoking will still continue! The UNIT.FlareGreen(), UNIT.FlareRed(), UNIT.FlareWhite(), UNIT.FlareYellow() methods will fire off a flare in the air with the corresponding color. Note that a flare is a one-off shot and its effect is of very short duration.

                      -

                      Position, Point

                      +

                      1.4) Location Position, Point

                      The UNIT class provides methods to obtain the current point or position of the DCS Unit. -The UNIT.GetPointVec2(), UNIT.GetPointVec3() will obtain the current location of the DCS Unit in a Vec2 (2D) or a Vec3 (3D) vector respectively. -If you want to obtain the complete 3D position including oriëntation and direction vectors, consult the UNIT.GetPositionVec3() method respectively.

                      +The UNIT.GetPointVec2(), UNIT.GetPointVec3() will obtain the current location of the DCS Unit in a Vec2 (2D) or a point in a Vec3 (3D) vector respectively. +If you want to obtain the complete 3D position including oriëntation and direction vectors, consult the UNIT.GetPositionVec3() method respectively.

                      -

                      Alive

                      +

                      1.5) Test if alive

                      The UNIT.IsAlive(), UNIT.IsActive() methods determines if the DCS Unit is alive, meaning, it is existing and active.

                      -

                      Test for other units in radius

                      -

                      One can test if another DCS Unit is within a given radius of the current DCS Unit, by using the UNIT.OtherUnitInRadius() method.

                      - -

                      More functions will be added

                      -

                      During the MOOSE development, more functions will be added. A complete list of the current functions is below.

                      - +

                      1.6) Test for proximity

                      +

                      The UNIT class contains methods to test the location or proximity against zones or other objects.

                      +

                      1.6.1) Zones

                      +

                      To test whether the Unit is within a zone, use the UNIT.IsInZone() or the UNIT.IsNotInZone() methods. Any zone can be tested on, but the zone must be derived from Zone#ZONE_BASE.

                      +

                      1.6.2) Units

                      +

                      Test if another DCS Unit is within a given radius of the current DCS Unit, use the UNIT.OtherUnitInRadius() method.

                      Global(s)

                      @@ -384,6 +379,18 @@ If you want to obtain the complete 3D position including ori
    + + + + + + + + @@ -1487,6 +1494,60 @@ The DCS Unit is not existing or alive.

    + +UNIT:IsInZone(Zone) + +
    +
    + +

    Returns true if the unit is within a Zone.

    + +

    Parameter

    + +

    Return value

    + +

    #boolean: +Returns true if the unit is within the Zone#ZONE_BASE

    + +
    +
    +
    +
    + + +UNIT:IsNotInZone(Zone) + +
    +
    + +

    Returns true if the unit is not within a Zone.

    + +

    Parameter

    + +

    Return value

    + +

    #boolean: +Returns true if the unit is not within the Zone#ZONE_BASE

    + +
    +
    +
    +
    + UNIT:OtherUnitInRadius(AwaitUnit, Radius) diff --git a/Moose Training/Documentation/Zone.html b/Moose Training/Documentation/Zone.html index 2040352cb..6f2b1a322 100644 --- a/Moose Training/Documentation/Zone.html +++ b/Moose Training/Documentation/Zone.html @@ -71,7 +71,6 @@

    Module Zone

    -

    ZONE Classes

    This module contains the ZONE classes, inherited from Zone#ZONE_BASE.

    @@ -103,7 +102,6 @@
  • Zone#ZONE_POLYGON: The ZONE_POLYGON class defined by a sequence of Group#GROUP waypoints within the Mission Editor, forming a polygon.
    • -

    Polymorphic methods

    Each zone implements two polymorphic functions defined in Zone#ZONE_BASE:

    +

    1) Zone#ZONE_BASE class, extends Base#BASE

    +

    The ZONE_BASE class defining the base for all other zone classes.

    + +

    2) Zone#ZONE_RADIUS class, extends Zone#ZONE_BASE

    +

    The ZONE_RADIUS class defined by a zone name, a location and a radius.

    + +

    3) Zone#ZONE class, extends Zone#ZONE_RADIUS

    +

    The ZONE class, defined by the zone name as defined within the Mission Editor.

    + +

    4) Zone#ZONE_UNIT class, extends Zone#ZONE_RADIUS

    +

    The ZONE_UNIT class defined by a zone around a Unit#UNIT with a radius.

    + +

    5) Zone#ZONE_POLYGON class, extends Zone#ZONE_BASE

    +

    The ZONE_POLYGON class defined by a sequence of Group#GROUP waypoints within the Mission Editor, forming a polygon.

    +

    Global(s)

    GROUP:IsAlive()

    Returns if the DCS Group is alive.

    +
    GROUP:IsCompletelyInZone(Zone) +

    Returns true if all units of the group are within a Zone.
    GROUP:IsHelicopter()

    Returns if the DCS Group contains Helicopters.

    +
    GROUP:IsNotInZone(Zone) +

    Returns true if none of the group units of the group are within a Zone.

    +
    GROUP:IsPartlyInZone(Zone) +

    Returns true if some units of the group are within a Zone.
    GROUP:TaskCombo(DCSTasks) -

    Return a Combo Task taking an array of Tasks

    +

    Return a Combo Task taking an array of Tasks.
    GROUP:TaskCondition(time, userFlag, userFlagValue, condition, duration, lastWayPoint) -

    Return a condition section for a controlled task

    +

    Return a condition section for a controlled task.
    GROUP:TaskControlled(DCSTask, DCSStopCondition) -

    Return a Controlled Task taking a Task and a TaskCondition

    +

    Return a Controlled Task taking a Task and a TaskCondition.
    GROUP:TaskEmbarkToTransportAtVec2(Point, Radius)GROUP:TaskEmbarkToTransport(Point, Radius)

    Move to a defined Vec2 Point, and embark to a group when arrived within a defined Radius.
    GROUP:TaskEmbarkingAtVec2(Point, Duration, EmbarkingGroup)GROUP:TaskEmbarking(Point, Duration, EmbarkingGroup) -

    Move the group to a Vec2 Point, wait for a defined duration and embark a group.

    +

    (AIR) Move the group to a Vec2 Point, wait for a defined duration and embark a group.
    GROUP:TaskLandAtZone(Zone, Duration, RandomPoint) -

    (AIR) Land the group at a @{Zone#ZONE).

    +

    (AIR) Land the group at a @{Zone#ZONE_RADIUS).
    GROUP:TaskMission(TaskMission) -

    Return a Misson task from a mission template.

    +

    (AIR + GROUND) Return a mission task from a mission template.
    GROUP:TaskOrbitCircle(Altitude, Speed) -

    (AIR) Orbit at the current position of the first unit of the group at a specified alititude

    +

    (AIR) Orbit at the current position of the first unit of the group at a specified alititude.
    GROUP:TaskRouteToVec2(Point, Speed) -

    Make the DCS Group to fly to a given point and hover.

    +

    (AIR + GROUND) Make the Group move to fly to a given point.
    GROUP:TaskRouteToVec3(Point, Speed) -

    Make the DCS Group to fly to a given point and hover.

    +

    (AIR + GROUND) Make the Group move to a given point.
    GROUP:TaskRouteToZone(Zone, Randomize, Speed, Formation) -

    Route the group to a given zone.

    +

    (AIR + GROUND) Route the group to a given zone.
    GROUP:TaskWrappedAction(DCSCommand, Index) -

    Return a WrappedAction Task taking a Command

    +

    Return a WrappedAction Task taking a Command.
    UNIT:IsAlive()

    Returns if the unit is alive.

    +
    UNIT:IsInZone(Zone) +

    Returns true if the unit is within a Zone.

    +
    UNIT:IsNotInZone(Zone) +

    Returns true if the unit is not within a Zone.
    @@ -172,13 +185,13 @@ @@ -466,16 +479,22 @@ The name of the zone as defined within the mission editor.

    - +

    Returns if a location is within the zone.

    Parameter

    +

    Return value

    + +

    #boolean: +true if the location is within the zone.

    +
    @@ -487,16 +506,22 @@ The name of the zone as defined within the mission editor.

    - +

    Returns if a point is within the zone.

    Parameter

    +

    Return value

    + +

    #boolean: +true if the point is within the zone.

    +
    diff --git a/Moose Training/Documentation/index.html b/Moose Training/Documentation/index.html index 891e8acef..7fe1edb39 100644 --- a/Moose Training/Documentation/index.html +++ b/Moose Training/Documentation/index.html @@ -105,7 +105,7 @@
    @@ -231,7 +231,7 @@ @@ -339,14 +339,7 @@ @@ -358,7 +351,6 @@
    ZONE_BASE:IsPointVec2InZone(PointVec2) - +

    Returns if a location is within the zone.
    ZONE_BASE:IsPointVec3InZone(PointVec3) - +

    Returns if a point is within the zone.
    Client -

    The CLIENT models client units in multi player missions.

    +

    This module contains the CLIENT class.
    Group -

    GROUP class.

    +

    This module contains the GROUP class.
    Unit -

    UNIT Class

    - -

    UNIT class

    -

    The UNIT class is a wrapper class to handle the DCS Unit objects:

    - -
      -
    • Support all DCS Unit APIs.
      • -
    +

    This module contains the UNIT class.
    Zone -

    ZONE Classes

    This module contains the ZONE classes, inherited from Zone#ZONE_BASE.