From 7e1ab1e6b0affda5eb2f73bfd4f76596fc132616 Mon Sep 17 00:00:00 2001 From: Applevangelist Date: Thu, 18 Aug 2022 16:00:46 +0200 Subject: [PATCH] #PLAYERTASKCONTROLLER * Added base documentation --- Moose Development/Moose/Ops/PlayerTask.lua | 237 ++++++++++++++++++++- 1 file changed, 227 insertions(+), 10 deletions(-) diff --git a/Moose Development/Moose/Ops/PlayerTask.lua b/Moose Development/Moose/Ops/PlayerTask.lua index dfc081059..09630df0e 100644 --- a/Moose Development/Moose/Ops/PlayerTask.lua +++ b/Moose Development/Moose/Ops/PlayerTask.lua @@ -3,7 +3,9 @@ -- ## Main Features: -- -- * Simplifies defining and executing Player tasks --- * FSM events when a mission is done, successful or failed +-- * FSM events when a mission is added, done, successful or failed, replanned +-- * Ready to use SRS and localization +-- * Mission locations can be smoked, flared and marked on the map -- -- === -- @@ -17,10 +19,16 @@ -- -- === -- @module Ops.PlayerTask --- @image OPS_PlayerTask.png +-- @image OPS_Auftrag.png -- @date Last Update August 2022 +do +------------------------------------------------------------------------------------------------------------------- +-- PLAYERTASK +-- TODO: PLAYERTASK +------------------------------------------------------------------------------------------------------------------- + --- PLAYERTASK class. -- @type PLAYERTASK -- @field #string ClassName Name of the class. @@ -40,13 +48,8 @@ -- @field #table conditionFailure = {}, -- @field Ops.PlayerTask#PLAYERTASKCONTROLLER TaskController -- @field #number timestamp --- -- @extends Core.Fsm#FSM -------------------------------------------------------------------------------------------------------------------- --- PLAYERTASK --- TODO: PLAYERTASK -------------------------------------------------------------------------------------------------------------------- --- Global PlayerTaskNr counter _PlayerTaskNr = 0 @@ -661,7 +664,12 @@ function PLAYERTASK:onafterFailed(From, Event, To) end return self end +------------------------------------------------------------------------------------------------------------------- +-- END PLAYERTASK +------------------------------------------------------------------------------------------------------------------- +end +do ------------------------------------------------------------------------------------------------------------------- -- PLAYERTASKCONTROLLER -- TODO: PLAYERTASKCONTROLLER @@ -690,10 +698,194 @@ end -- @field #table WhiteList -- @field Core.TextAndSound#TEXTANDSOUND gettext -- @field #string locale --- +-- @extends Core.Fsm#FSM + --- +-- +-- *It is our attitude at the beginning of a difficult task which, more than anything else, will affect its successful outcome.* (William James) +-- +-- === +-- +-- ## PLAYERTASKCONTROLLER +-- +-- * Simplifies defining and executing Player tasks +-- * FSM events when a mission is added, done, successful or failed, replanned +-- * Ready to use SRS and localization +-- * Mission locations can be smoked, flared and marked on the map +-- +-- ## 1 Overview +-- +-- PLAYERTASKCONTROLLER is used to auto-create (optional) and control tasks for players. It can be set up as Air-to-Ground (A2G, main focus), Air-to-Ship (A2S) or Air-to-Air (A2A) controller. +-- For the latter task type, also have a look at the @{Ops.AwacsGroup#AWACS} class which allows for more complex scenarios. +-- One task at a time can be joined by the player from the F10 menu. A task can be joined by multiple players. Once joined, task information is available via the F10 menu, the task location +-- can be marked on the map and for A2G/S targets, the target can be marked with smoke and flares. +-- +-- For the mission designer, tasks can be auto-created by means of detection with the integrated @{Ops.Intelligence#INTEL} class setup, or be manually added to the task queue. +-- +-- ## 2 Task Types +-- +-- Targets can be of types GROUP, SET\_GROUP, UNIT, SET\_UNIT, STATIC, SET\_STATIC, AIRBASE, ZONE or COORDINATE. The system will auto-create tasks for players from these targets. +-- Tasks are created as @{Ops.PlayerTask#PLAYERTASK} objects, which leverage @{Ops.Target#TARGET} for the management of the actual target. The system creates these task types +-- from the target objects: +-- +-- * A2A - AUFTRAG.Type.INTERCEPT +-- * A2S - AUFTRAG.Type.ANTISHIP +-- * A2G - AUFTRAG.Type.CAS, AUFTRAG.Type.BAI, AUFTRAG.Type.SEAD, AUFTRAG.Type.BOMBING, AUFTRAG.Type.BOMBRUNWAY +-- +-- Task types are derived from @{Ops.Auftrag#AUFTRAG}: +-- +-- * CAS - Close air support, created to attack ground units, where friendly ground units are around the location in a bespoke radius (default: 500m/1km diameter) +-- * BAI - Battlefield air interdiction, same as above, but no friendlies around +-- * SEAD - Same as CAS, but the enemy ground units field AAA, SAM or EWR units +-- * Bombing - Against static targets +-- * Bomb Runway - Against Airbase runways (in effect, drop bombs over the runway) +-- * ZONE and COORDINATE - Targets will be scanned for GROUND or STATIC enemy units and tasks created from these +-- * Intercept - Any airborne targets, if the controller is of type "A2A" +-- * Anti-Ship - Any ship targets, if the controller is of type "A2S" +-- +-- ## 3 Task repetition +-- +-- On failure, tasks will be replanned by default for a maximum of 5 times. +-- +-- ## 4 SETTINGS, SRS and language options (localization) +-- +-- The system can optionally communicate to players via SRS. Also localization is available, both "en" and "de" has been build in already. +-- Player and global @{Core.Settings#SETTINGS} for coordinates will be observed. +-- +-- ## 5 Setup +-- +-- A basic setup is very simple: +-- +-- -- Settings - we want players to have a settings menu, be on imperial measures, and get directions as BR +-- _SETTINGS:SetPlayerMenuOn() +-- _SETTINGS:SetImperial() +-- _SETTINGS:SetA2G_BR() +-- +-- -- Set up the A2G task controller for the blue side named "82nd Airborne" +-- local taskmanager = PLAYERTASKCONTROLLER:New("82nd Airborne",coalition.side.BLUE,PLAYERTASKCONTROLLER.Type.A2G) +-- +-- -- set locale to English +-- taskmanager:SetLocale("en") +-- +-- -- Set up detection with grup names *containing* "Blue Recce", these will add targets to our controller via detection. Can be e.g. a drone. +-- taskmanager:SetupIntel("Blue Recce") +-- +-- -- Add a single Recce group name "Blue Humvee" +-- taskmanager:AddAgent(GROUP:FindByName("Blue Humvee")) +-- +-- -- Set the callsign for SRS and Menu name to be "Groundhog" +-- taskmanager:SetMenuName("Groundhog") +-- +-- -- Add accept- and reject-zones for detection +-- -- Accept zones are handy to limit e.g. the engagement to a certain zone. The example is a round, mission editor created zone named "AcceptZone" +-- taskmanager:AddAcceptZone(ZONE:New("AcceptZone")) +-- +-- -- Reject zones are handy to create borders. The example is a ZONE_POLYGON, created in the mission editor, late activated with waypoints, +-- -- named "AcceptZone#ZONE_POLYGON" +-- taskmanager:AddRejectZone(ZONE:FindByName("RejectZone")) +-- +-- -- Set up using SRS for messaging +-- local hereSRSPath = "C:\\Program Files\\DCS-SimpleRadio-Standalone" +-- local hereSRSPort = 5002 +-- -- local hereSRSGoogle = "C:\\Program Files\\DCS-SimpleRadio-Standalone\\yourkey.json" +-- taskmanager:SetSRS({130,255},{radio.modulation.AM,radio.modulation.AM},hereSRSPath,"female","en-GB",hereSRSPort,"Microsoft Hazel Desktop",0.7,hereSRSGoogle) +-- +-- -- Controller will announce itself under these broadcast frequencies, handy to use cold-start frequencies here of your aircraft +-- taskmanager:SetSRSBroadcast({127.5,305},{radio.modulation.AM,radio.modulation.AM}) +-- +-- -- Example: Manually add an AIRBASE as a target +-- taskmanager:AddTarget(AIRBASE:FindByName(AIRBASE.Caucasus.Senaki_Kolkhi)) +-- +-- -- Example: Manually add a COORDINATE as a target +-- taskmanager:AddTarget(GROUP:FindByName("Scout Coordinate"):GetCoordinate()) +-- +-- -- Set a whitelist for tasks, e.g. skip SEAD tasks +-- taskmanager:SetTaskWhiteList({AUFTRAG.Type.CAS, AUFTRAG.Type.BAI, AUFTRAG.Type.BOMBING, AUFTRAG.Type.BOMBRUNWAY}) +-- +-- -- Set target radius +-- taskmanager:SetTargetRadius(1000) +-- +-- ## 6 Localization +-- +-- Localization for English and German texts are build-in. Default setting is English. Change with @{#PLAYERTASKCONTROLLER.SetLocale}() +-- +-- ### 6.1 Adding Localization +-- +-- A list of fields to be defined follows below. **Note** that in some cases `string.format()` is used to format texts for screen and SRS. +-- Hence, the `%d`, `%s` and `%f` special characters need to appear in the exact same amount and order of appearance in the localized text or it will create errors. +-- To add a localization, the following texts need to be translated and set in your mission script **before** @{#PLAYERTASKCONTROLLER.New}(): +-- +-- PLAYERTASKCONTROLLER.Messages = { +-- EN = { +-- TASKABORT = "Task aborted!", +-- NOACTIVETASK = "No active task!", +-- FREQUENCIES = "frequencies ", +-- FREQUENCY = "frequency %.3f", +-- BROADCAST = "%s, %s, switch to %s for task assignment!", +-- CASTTS = "close air support", +-- SEADTTS = "suppress air defense", +-- BOMBTTS = "bombing", +-- BAITTS = "battle field air interdiction", +-- ANTISHIPTTS = "anti-ship", +-- INTERCEPTTS = "intercept", +-- BOMBRUNWAYTTS = "bomb runway", +-- HAVEACTIVETASK = "You already have one active task! Complete it first!", +-- PILOTJOINEDTASK = "%s, pilot %s joined task %03d", +-- TASKNAME = "%s Task ID %03d", +-- TASKNAMETTS = "%s Task ID %03d", +-- THREATHIGH = "high", +-- THREATMEDIUM = "medium", +-- THREATLOW = "low", +-- THREATTEXT = "%s\nThreat: %s\nTargets left: %d\nCoord: %s", +-- THREATTEXTTTS = "%s, %s. Target information for %s. Threat level %s. Targets left %d. Target location %s.", +-- MARKTASK = "%s, copy pilot %s, task %03d location marked on map!", +-- SMOKETASK = "%s, copy pilot %s, task %03d location smoked!", +-- FLARETASK = "%s, copy pilot %s, task %03d location illuminated!", +-- ABORTTASK = "%s, all stations, pilot %s aborted task %03d!", +-- UNKNOWN = "Unknown", +-- MENUTASKING = " Tasking ", +-- MENUACTIVE = "Active Task", +-- MENUINFO = "Info", +-- MENUMARK = "Mark on map", +-- MENUSMOKE = "Smoke", +-- MENUFLARE = "Flare", +-- MENUABORT = "Abort", +-- MENUJOIN = "Join Task", +-- MENUTASKNO = "TaskNo", +-- MENUNOTASKS = "Currently no tasks available.", +-- TASKCANCELLED = "Task #%03d %s is cancelled!", +-- TASKCANCELLEDTTS = "%s, task %03d %s is cancelled!", +-- TASKSUCCESS = "Task #%03d %s completed successfully!", +-- TASKSUCCESSTTS = "%s, task %03d %s completed successfully!", +-- TASKFAILED = "Task #%03d %s was a failure!", +-- TASKFAILEDTTS = "%s, task %03d %s was a failure!", +-- TASKFAILEDREPLAN = "Task #%03d %s was a failure! Replanning!", +-- TASKFAILEDREPLANTTS = "%s, task %03d %s was a failure! Replanning!", +-- TASKADDED = "%s has a new task %s", +-- PILOTS = "\nPilot(s): ", +-- PILOTSTTS = ". Pilot(s): ", +-- }, +-- +-- e.g. +-- +-- taskmanager.Messages = { +-- FR = { +-- TASKABORT = "Tâche abandonnée!", +-- NOACTIVETASK = "Aucune tâche active!", +-- FREQUENCIES = "fréquences ", +-- FREQUENCY = "fréquence %.3f", +-- BROADCAST = "%s, %s, passer au %s pour l'attribution des tâches!", +-- ... +-- TASKADDED = "%s a une nouvelle tâche %s", +-- PILOTS = "\nPilote(s): ", +-- PILOTSTTS = ". Pilote(s): ", +-- }, +-- +-- and then `taskmanager:SetLocale("fr")` **after** @{#PLAYERTASKCONTROLLER.New}() in your script. +-- +-- -- @field #PLAYERTASKCONTROLLER PLAYERTASKCONTROLLER = { ClassName = "PLAYERTASKCONTROLLER", @@ -827,7 +1019,7 @@ PLAYERTASKCONTROLLER.Messages = { --- PLAYERTASK class version. -- @field #string version -PLAYERTASKCONTROLLER.version="0.1.16" +PLAYERTASKCONTROLLER.version="0.1.17" --- Constructor -- @param #PLAYERTASKCONTROLLER self @@ -958,6 +1150,9 @@ function PLAYERTASKCONTROLLER:New(Name, Coalition, Type, ClientFilter) end +--- [Internal] Init localization +-- @param #PLAYERTASKCONTROLLER self +-- @return #PLAYERTASKCONTROLLER self function PLAYERTASKCONTROLLER:_InitLocalization() self:T(self.lid.."_InitLocalization") self.gettext = TEXTANDSOUND:New("PLAYERTASKCONTROLLER","en") -- Core.TextAndSound#TEXTANDSOUND @@ -973,7 +1168,25 @@ function PLAYERTASKCONTROLLER:_InitLocalization() return self end ---- [internal] Event handling +--- [User] Set repetition options for tasks +-- @param #PLAYERTASKCONTROLLER self +-- @param #boolean OnOff Set to `true` to switch on and `false` to switch off (defaults to true) +-- @param #number Repeats Number of repeats (defaults to 5) +-- @return #PLAYERTASKCONTROLLER self +-- @usage `taskmanager:SetTaskRepetition(true, 5)` +function PLAYERTASKCONTROLLER:SetTaskRepetition(OnOff, Repeats) + self:T(self.lid.."SetTaskRepetition") + if OnOff then + self.repeatonfailed = true + self.repeattimes = Repeats or 5 + else + self.repeatonfailed = false + self.repeattimes = Repeats or 5 + end + return self +end + +--- [Internal] Event handling -- @param #PLAYERTASKCONTROLLER self -- @param Core.Event#EVENTDATA EventData -- @return #PLAYERTASKCONTROLLER self @@ -2107,4 +2320,8 @@ function PLAYERTASKCONTROLLER:onafterStop(From, Event, To) self:UnHandleEvent(EVENTS.PlayerEnterAircraft) return self end +------- +-- END PLAYERTASKCONTROLLER +----- +end