Documentation

Moose Development/Moose/Core/Point.lua

@@ -1,5 +1,11 @@
---- **Core** -- **POINT\_VEC** classes define an **extensive API** to **manage 3D points** in the simulation space.
+--- **Core** -- Defines an **extensive API** to **manage 3D points** in the DCS World 3D simulation space.
 --
+-- **Features:**
+-- 
+--   * Provides a COORDINATE class, which allows to manage points in 3D space and perform various operations on it.
+--   * Provides a POINT\_VEC2 class, which is derived from COORDINATE, and allows to manage points in 3D space, but from a Lat/Lon and Altitude perspective.
+--   * Provides a POINT\_VEC3 class, which is derived from COORDINATE, and allows to manage points in 3D space, but from a X, Z and Y vector perspective.
+-- 
 -- ===
 --
 -- # Demo Missions
@@ -38,29 +44,20 @@ do -- COORDINATE
   
   --- Defines a 3D point in the simulator and with its methods, you can use or manipulate the point in 3D space.
   --
-  -- ## COORDINATE constructor
+  -- # 1) Create a COORDINATE object.
   --
-  -- A new COORDINATE object can be created with:
+  -- A new COORDINATE object can be created with 3 various methods:
   --
-  --  * @{#COORDINATE.New}(): a 3D point.
+  --  * @{#COORDINATE.New}(): from a 3D point.
-  --  * @{#COORDINATE.NewFromVec2}(): a 2D point created from a @{DCS#Vec2}.
+  --  * @{#COORDINATE.NewFromVec2}(): from a @{DCS#Vec2} and possible altitude.
-  --  * @{#COORDINATE.NewFromVec3}(): a 3D point created from a @{DCS#Vec3}.
+  --  * @{#COORDINATE.NewFromVec3}(): from a @{DCS#Vec3}.
-  --
-  -- ## Create waypoints for routes
-  --
-  -- A COORDINATE can prepare waypoints for Ground and Air groups to be embedded into a Route.
-  --
-  --   * @{#COORDINATE.WaypointAir}(): Build an air route point.
-  --   * @{#COORDINATE.WaypointGround}(): Build a ground route point.
-  --
-  -- Route points can be used in the Route methods of the @{Wrapper.Group#GROUP} class.
   --
   --
-  -- ## Smoke, flare, explode, illuminate
+  -- # 2) Smoke, flare, explode, illuminate at the coordinate.
   --
   -- At the point a smoke, flare, explosion and illumination bomb can be triggered. Use the following methods:
   --
-  -- ### Smoke
+  -- ## 2.1) Smoke
   --
   --   * @{#COORDINATE.Smoke}(): To smoke the point in a certain color.
   --   * @{#COORDINATE.SmokeBlue}(): To smoke the point in blue.
@@ -69,7 +66,7 @@ do -- COORDINATE
   --   * @{#COORDINATE.SmokeWhite}(): To smoke the point in white.
   --   * @{#COORDINATE.SmokeGreen}(): To smoke the point in green.
   --
-  -- ### Flare
+  -- ## 2.2) Flare
   --
   --   * @{#COORDINATE.Flare}(): To flare the point in a certain color.
   --   * @{#COORDINATE.FlareRed}(): To flare the point in red.
@@ -77,18 +74,19 @@ do -- COORDINATE
   --   * @{#COORDINATE.FlareWhite}(): To flare the point in white.
   --   * @{#COORDINATE.FlareGreen}(): To flare the point in green.
   --
-  -- ### Explode
+  -- ## 2.3) Explode
   --
   --   * @{#COORDINATE.Explosion}(): To explode the point with a certain intensity.
   --
-  -- ### Illuminate
+  -- ## 2.4) Illuminate
   --
   --   * @{#COORDINATE.IlluminationBomb}(): To illuminate the point.
   --
   --
-  -- ## Markings
+  -- # 3) Create markings on the map.
   -- 
-  -- Place markers (text boxes with clarifications for briefings, target locations or any other reference point) on the map for all players, coalitions or specific groups:
+  -- Place markers (text boxes with clarifications for briefings, target locations or any other reference point) 
+  -- on the map for all players, coalitions or specific groups:
   -- 
   --   * @{#COORDINATE.MarkToAll}(): Place a mark to all players.
   --   * @{#COORDINATE.MarkToCoalition}(): Place a mark to a coalition.
@@ -96,47 +94,99 @@ do -- COORDINATE
   --   * @{#COORDINATE.MarkToCoalitionBlue}(): Place a mark to the blue coalition.
   --   * @{#COORDINATE.MarkToGroup}(): Place a mark to a group (needs to have a client in it or a CA group (CA group is bugged)).
   --   * @{#COORDINATE.RemoveMark}(): Removes a mark from the map.
-  --   
+  -- 
-  --
+  -- # 4) Coordinate calculation methods.
-  -- ## 3D calculation methods
   --
   -- Various calculation methods exist to use or manipulate 3D space. Find below a short description of each method:
   --
-  -- ### Distance
+  -- ## 4.1) Get the distance between 2 points.
   --
   --   * @{#COORDINATE.Get3DDistance}(): Obtain the distance from the current 3D point to the provided 3D point in 3D space.
   --   * @{#COORDINATE.Get2DDistance}(): Obtain the distance from the current 3D point to the provided 3D point in 2D space.
   --
-  -- ### Angle
+  -- ## 4.2) Get the angle.
   --
   --   * @{#COORDINATE.GetAngleDegrees}(): Obtain the angle in degrees from the current 3D point with the provided 3D direction vector.
   --   * @{#COORDINATE.GetAngleRadians}(): Obtain the angle in radians from the current 3D point with the provided 3D direction vector.
   --   * @{#COORDINATE.GetDirectionVec3}(): Obtain the 3D direction vector from the current 3D point to the provided 3D point.
   --
-  -- ### Translation
+  -- ## 4.3) Coordinate translation.
   --
   --   * @{#COORDINATE.Translate}(): Translate the current 3D point towards an other 3D point using the given Distance and Angle.
   --
-  -- ### Get the North correction of the current location
+  -- ## 4.4) Get the North correction of the current location.
   --
   --   * @{#COORDINATE.GetNorthCorrection}(): Obtains the north correction at the current 3D point.
   --
-  --
+  -- ## 4.5) Point Randomization
-  -- ## Point Randomization
   --
   -- Various methods exist to calculate random locations around a given 3D point.
   --
   --   * @{#COORDINATE.GetRandomVec2InRadius}(): Provides a random 2D vector around the current 3D point, in the given inner to outer band.
   --   * @{#COORDINATE.GetRandomVec3InRadius}(): Provides a random 3D vector around the current 3D point, in the given inner to outer band.
+  -- 
+  -- ## 4.6) LOS between coordinates.
+  -- 
+  -- Calculate if the coordinate has Line of Sight (LOS) with the other given coordinate.
+  -- Mountains, trees and other objects can be positioned between the two 3D points, preventing visibilty in a straight continuous line.
+  -- The method @{#COORDINATE.IsLOS}() returns if the two coodinates have LOS.
+  -- 
+  -- ## 4.7) Check the coordinate position.
+  -- 
+  -- Various methods are available that allow to check if a coordinate is:
+  -- 
+  --   * @{#COORDINATE.IsInRadius}(): in a give radius.
+  --   * @{#COORDINATE.IsInSphere}(): is in a given sphere.
+  --   * @{#COORDINATE.IsAtCoordinate2D}(): is in a given coordinate within a specific precision.
+  -- 
+  --   
+  --
+  -- # 5) Measure the simulation environment at the coordinate.
+  -- 
+  -- ## 5.1) Weather specific.
+  -- 
+  -- Within the DCS simulator, a coordinate has specific environmental properties, like wind, temperature, humidity etc.
+  -- 
+  --   * @{#COORDINATE.GetWind}(): Retrieve the wind at the specific coordinate within the DCS simulator.
+  --   * @{#COORDINATE.GetTemperature}(): Retrieve the temperature at the specific height within the DCS simulator.
+  --   * @{#COORDINATE.GetPressure}(): Retrieve the pressure at the specific height within the DCS simulator.
+  -- 
+  -- ## 5.2) Surface specific.
+  -- 
+  -- Within the DCS simulator, the surface can have various objects placed at the coordinate, and the surface height will vary.
+  -- 
+  --   * @{#COORDINATE.GetLandHeight}(): Retrieve the height of the surface (on the ground) within the DCS simulator.
+  --   * @{#COORDINATE.GetSurfaceType}(): Retrieve the surface type (on the ground) within the DCS simulator.
+  --
+  -- # 6) Create waypoints for routes.
+  --
+  -- A COORDINATE can prepare waypoints for Ground and Air groups to be embedded into a Route.
+  --
+  --   * @{#COORDINATE.WaypointAir}(): Build an air route point.
+  --   * @{#COORDINATE.WaypointGround}(): Build a ground route point.
+  --
+  -- Route points can be used in the Route methods of the @{Wrapper.Group#GROUP} class.
+  --
+  -- ## 7) Manage the roads.
+  -- 
+  -- Important for ground vehicle transportation and movement, the method @{#COORDINATE.GetClosestPointToRoad}() will calculate
+  -- the closest point on the nearest road.
+  -- 
+  -- In order to use the most optimal road system to transport vehicles, the method @{#COORDINATE.GetPathOnRoad}() will calculate
+  -- the most optimal path following the road between two coordinates.
+  --   
   --
   --
-  -- ## Metric system
+  --
+  --
+  -- ## 8) Metric or imperial system
   --
   --   * @{#COORDINATE.IsMetric}(): Returns if the 3D point is Metric or Nautical Miles.
   --   * @{#COORDINATE.SetMetric}(): Sets the 3D point to Metric or Nautical Miles.
   --
   --
-  -- ## Coorinate text generation
+  -- ## 9) Coordinate text generation
+  -- 
   --
   --   * @{#COORDINATE.ToStringBR}(): Generates a Bearing & Range text in the format of DDD for DI where DDD is degrees and DI is distance.
   --   * @{#COORDINATE.ToStringLL}(): Generates a Latutude & Longutude text.

Moose Development/Moose/Tasking/Task.lua

@@ -80,9 +80,9 @@
 -- Depending on the task progress, a **scoring** can be allocated to award pilots of the achievements made.
 -- The scoring is fully flexible, and different levels of awarding can be provided depending on the task type and complexity.
 -- 
--- ## 1. Task Statuses
+-- # 1) Task Statuses
 -- 
--- ### 1.1. Task status overview.
+-- ## 1.1) Task status overview.
 -- 
 -- A task has a state, reflecting the progress and completion of the task:
 -- 
@@ -93,12 +93,18 @@
 --   - **Abort**: Expresses that the task is aborted by by the player using the abort menu.
 --   - **Cancelled**: Expresses that the task is cancelled by HQ or through a logical situation where a cancellation of the task is required.
 -- 
+-- 
 -- A normal flow of task status would evolve from the **Planned** state, to the **Assigned** state ending either in a **Success** or a **Failed** state.
+-- 
+--      Planned -> Assigned -> Success
+--                          -> Failed
+--                          
 -- The state completion is by default set to **Success**, if the goals of the task have been reached, but can be overruled by a goal method.
 -- 
--- Depending on the tactical situation, a task can be **Rejected** or **Cancelled** by the mission governer.
+-- Depending on the tactical situation, a task can be **Cancelled** by the mission governer.
 -- It is actually the mission designer who has the flexibility to decide at which conditions a task would be set to **Success**, **Failed** or **Cancelled**.
--- It all depends on the task goals, and the phase/evolution of the task conditions that would accomplish the goals.
+-- This decision all depends on the task goals, and the phase/evolution of the task conditions that would accomplish the goals.
+-- 
 -- For example, if the task goal is to merely destroy a target, and the target is mid-mission destroyed by another event than the pilot destroying the target,
 -- the task goal could be set to **Failed**, or .. **Cancelled** ...
 -- However, it could very well be also acceptable that the task would be flagged as **Success**.
@@ -106,7 +112,7 @@
 -- The tasking mechanism governs beside the progress also a scoring mechanism, and in case of goal completion without any active pilot involved
 -- in the execution of the task, could result in a **Success** task completion status, but no score would be awared, as there were no players involved. 
 -- 
--- ### 1.2. Task status events.
+-- ## 1.2) Task status events.
 -- 
 -- The task statuses can be set by using the following methods:
 -- 
@@ -119,12 +125,12 @@
 -- The mentioned derived TASK_ classes are implementing the task status transitions out of the box.
 -- So no extra logic needs to be written.
 --   
--- ## 2. Goal conditions for a task.
+-- # 2) Goal conditions for a task.
 -- 
 -- Every 30 seconds, a @{#Task.Goal} trigger method is fired. 
 -- You as a mission designer, can capture the **Goal** event trigger to check your own task goal conditions and take action!
 -- 
--- ### 2.1. Goal event handler `OnAfterGoal()`.
+-- ## 2.1) Goal event handler `OnAfterGoal()`.
 -- 
 -- And this is a really great feature! Imagine a task which has **several conditions to check** before the task can move into **Success** state.
 -- You can do this with the OnAfterGoal method.
@@ -141,23 +147,30 @@
 --        end
 --      end
 -- 
--- So the @{#TASK.OnAfterGoal}() event handler would be called every 30 seconds automatically, and within this method, you can now check the conditions and take respective action.
+-- So the @{#TASK.OnAfterGoal}() event handler would be called every 30 seconds automatically, 
+-- and within this method, you can now check the conditions and take respective action.
 -- 
--- ### 2.2. Goal event trigger `Goal()`.
+-- ## 2.2) Goal event trigger `Goal()`.
 -- 
 -- If you would need to check a goal at your own defined event timing, then just call the @{#TASK.Goal}() method within your logic.
 -- The @{#TASK.OnAfterGoal}() event handler would then directly be called and would execute the logic. 
--- Note that you can also delay the goal check by using the delayed event trigger syntax `:__Goal( Dalay )`. 
+-- Note that you can also delay the goal check by using the delayed event trigger syntax `:__Goal( Delay )`. 
 -- 
 -- 
--- ## 3) Add scoring when reaching a certain task status:
+-- # 3) Add scoring when reaching a certain task status:
 -- 
 -- Upon reaching a certain task status in a task, additional scoring can be given. If the Mission has a scoring system attached, the scores will be added to the mission scoring.
 -- Use the method @{#TASK.AddScore}() to add scores when a status is reached.
 -- 
--- ## 1.4) Task briefing:
+-- # 4) Task briefing:
+-- 
+-- A task briefing is a text that is shown to the player when he is assigned to the task.
+-- The briefing is broadcasted by the command center owning the mission.
+-- 
+-- The briefing is part of the parameters in the @{#TASK.New}() constructor, 
+-- but can separately be modified later in your mission using the
+-- @{#TASK.SetBriefing}() method.
 -- 
--- A task briefing can be given that is shown to the player when he is assigned to the task.
 -- 
 -- @field #TASK TASK
 --