From 4452cbd2abf9a167add6fea9acd280c515e44825 Mon Sep 17 00:00:00 2001 From: Van De Velde Date: Fri, 29 Jun 2018 05:05:31 +0200 Subject: [PATCH] Documentation --- Moose Development/Moose/Core/Point.lua | 116 ++++++++++++++++------- Moose Development/Moose/Tasking/Task.lua | 39 +++++--- 2 files changed, 109 insertions(+), 46 deletions(-) diff --git a/Moose Development/Moose/Core/Point.lua b/Moose Development/Moose/Core/Point.lua index b98159460..191fbc050 100644 --- a/Moose Development/Moose/Core/Point.lua +++ b/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.NewFromVec2}(): a 2D point created from a @{DCS#Vec2}. - -- * @{#COORDINATE.NewFromVec3}(): a 3D point created 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. + -- * @{#COORDINATE.New}(): from a 3D point. + -- * @{#COORDINATE.NewFromVec2}(): from a @{DCS#Vec2} and possible altitude. + -- * @{#COORDINATE.NewFromVec3}(): from a @{DCS#Vec3}. -- -- - -- ## 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. - -- - -- - -- ## 3D calculation methods + -- + -- # 4) Coordinate 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. -- - -- - -- ## Point Randomization + -- ## 4.5) 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. diff --git a/Moose Development/Moose/Tasking/Task.lua b/Moose Development/Moose/Tasking/Task.lua index 3835621a3..7b645c2ad 100644 --- a/Moose Development/Moose/Tasking/Task.lua +++ b/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 --