Module Functional.AICSAR
Functional - AI CSAR system.
Features:
- Send out helicopters to downed pilots
- Rescues players and AI alike
- Coalition specific
- Starting from a FARP or Airbase
- Dedicated MASH zone
- Some FSM functions to include in your mission scripts
- Limit number of available helos
- SRS voice output via TTS or soundfiles
Example Missions:
Demo missions can be found on GitHub.
Author: Applevangelist
Last Update Sept 2023
Global(s)
Global AICSAR |
I once donated a pint of my finest red corpuscles to the great American Red Cross and the doctor opined my blood was very helpful; contained so much alcohol they could use it to sterilize their instruments. AICSAR ConceptFor an AI or human pilot landing with a parachute, a rescue mission will be spawned. |
I once donated a pint of my finest red corpuscles to the great American Red Cross and the doctor opined my blood was very helpful; contained so much alcohol they could use it to sterilize their instruments.
W.C.Fields
AICSAR Concept
For an AI or human pilot landing with a parachute, a rescue mission will be spawned.
The helicopter will fly to the pilot, pick him or her up, and fly back to a designated MASH (medical) zone, drop the pilot and then return to base. Operational maxdistance can be set as well as the landing radius around the downed pilot. Keep in mind that AI helicopters cannot hover-load at the time of writing, so rescue operations over water or in the mountains might not work. Optionally, if you have a CSAR operation with human pilots in your mission, you can set AICSAR to ignore missions when human helicopter pilots are around.
Setup
Setup is a one-liner:
-- @param #string Alias Name of this instance.
-- @param #number Coalition Coalition as in coalition.side.BLUE, can also be passed as "blue", "red" or "neutral"
-- @param #string Pilottemplate Pilot template name.
-- @param #string Helotemplate Helicopter template name. Set the template to "cold start". Hueys work best.
-- @param Wrapper.Airbase#AIRBASE FARP FARP object or Airbase from where to start.
-- @param Core.Zone#ZONE MASHZone Zone where to drop pilots after rescue.
local my_aicsar=AICSAR:New("Luftrettung",coalition.side.BLUE,"Downed Pilot","Rescue Helo",AIRBASE:FindByName("Test FARP"),ZONE:New("MASH"))
Options are
my_aicsar.maxdistance -- maximum operational distance in meters. Defaults to 50NM or 92.6km
my_aicsar.rescuezoneradius -- landing zone around downed pilot. Defaults to 200m
my_aicsar.autoonoff -- stop operations when human helicopter pilots are around. Defaults to true.
my_aicsar.verbose -- text messages to own coalition about ongoing operations. Defaults to true.
my_aicsar.limithelos -- limit available number of helos going on mission (defaults to true)
my_aicsar.helonumber -- number of helos available (default: 3)
my_aicsar.verbose -- boolean, set to `true`for message output on-screen
Radio output options
Radio messages, soundfile names and (for SRS) lengths are defined in three enumerators, so you can customize, localize messages and soundfiles to your liking:
Defaults are:
AICSAR.Messages = {
EN = {
INITIALOK = "Roger, Pilot, we hear you. Stay where you are, a helo is on the way!",
INITIALNOTOK = "Sorry, Pilot. You're behind maximum operational distance! Good Luck!",
PILOTDOWN = "Mayday, mayday, mayday! Pilot down at ", -- note that this will be appended with the position in MGRS
PILOTKIA = "Pilot KIA!",
HELODOWN = "CSAR Helo Down!",
PILOTRESCUED = "Pilot rescued!",
PILOTINHELO = "Pilot picked up!",
},
}
Correspondingly, sound file names are defined as these defaults:
AICSAR.RadioMessages = {
EN = {
INITIALOK = "initialok.ogg",
INITIALNOTOK = "initialnotok.ogg",
PILOTDOWN = "pilotdown.ogg",
PILOTKIA = "pilotkia.ogg",
HELODOWN = "helodown.ogg",
PILOTRESCUED = "pilotrescued.ogg",
PILOTINHELO = "pilotinhelo.ogg",
},
}
and these default transmission lengths in seconds:
AICSAR.RadioLength = {
EN = {
INITIALOK = 4.1,
INITIALNOTOK = 4.6,
PILOTDOWN = 2.6,
PILOTKIA = 1.1,
HELODOWN = 2.1,
PILOTRESCUED = 3.5,
PILOTINHELO = 2.6,
},
}
Radio output via SRS and Text-To-Speech (TTS)
Radio output can be done via SRS and Text-To-Speech. No extra sound files required!
Initially, Have a look at the guide on setting up SRS TTS for Moose.
The text from the AICSAR.Messages table above is converted on the fly to an .ogg-file, which is then played back via SRS on the selected frequency and mdulation.
Hint - the small black window popping up shortly is visible in Single-Player only.
To set up AICSAR for SRS TTS output, add e.g. the following to your script:
-- setup for google TTS, radio 243 AM, SRS server port 5002 with a google standard-quality voice (google cloud account required)
my_aicsar:SetSRSTTSRadio(true,"C:\\Program Files\\DCS-SimpleRadio-Standalone",243,radio.modulation.AM,5002,MSRS.Voices.Google.Standard.en_US_Standard_D,"en-US","female","C:\\Program Files\\DCS-SimpleRadio-Standalone\\google.json")
-- alternatively for MS Desktop TTS (voices need to be installed locally first!)
my_aicsar:SetSRSTTSRadio(true,"C:\\Program Files\\DCS-SimpleRadio-Standalone",243,radio.modulation.AM,5002,MSRS.Voices.Microsoft.Hazel,"en-GB","female")
-- define a different voice for the downed pilot(s)
my_aicsar:SetPilotTTSVoice(MSRS.Voices.Google.Standard.en_AU_Standard_D,"en-AU","male")
-- define another voice for the operator
my_aicsar:SetOperatorTTSVoice(MSRS.Voices.Google.Standard.en_GB_Standard_A,"en-GB","female")
Radio output via preproduced soundfiles
The easiest way to add a soundfile to your mission is to use the "Sound to..." trigger in the mission editor. This will effectively save your sound file inside of the .miz mission file. Example soundfiles are located on github
To customize or localize your texts and sounds, you can take e.g. the following approach to add a German language version:
-- parameters are: locale, ID, text, soundfilename, duration
my_aicsar.gettext:AddEntry("de","INITIALOK","Copy, Pilot, wir hören Sie. Bleiben Sie, wo Sie sind, ein Hubschrauber sammelt Sie auf!","okneu.ogg",5.0)
my_aicsar.locale = "de" -- plays and shows the defined German language texts and sound. Fallback is "en", if something is undefined.
Switch on radio transmissions via either SRS or "normal" DCS radio e.g. like so:
my_aicsar:SetSRSRadio(true,"C:\\Program Files\\DCS-SimpleRadio-Standalone",270,radio.modulation.AM,nil,5002)
or
my_aicsar:SetDCSRadio(true,300,radio.modulation.AM,GROUP:FindByName("FARP-Radio"))
See the function documentation for parameter details.
-
Type(s)
| Fields and Methods inherited from AICSAR | Description |
|---|---|
|
Default altitude setting for the helicopter FLIGHTGROUP 1500ft. |
|
|
Name of this class. |
|
|
[Internal] Sound output via non-SRS Radio. |
|
|
In case of UseEventEject wait this long until we spawn a landed pilot. |
|
|
[Internal] Create the Moose TextAndSoundEntries |
|
AICSAR:New(Alias, Coalition, Pilottemplate, Helotemplate, FARP, MASHZone) |
Function to create a new AICSAR object |
|
On after "HeloDown" event. |
|
|
On after "HeloOnDuty" event. |
|
AICSAR:OnAfterPilotDown(From, Event, To, Coordinate, InReach) |
On after "PilotDown" event. |
|
On after "PilotKIA" event. |
|
AICSAR:OnAfterPilotPickedUp(From, Event, To, Helo, CargoTable, Index) |
On after "PilotPickedUp" event. |
|
On after "PilotRescued" event. |
|
AICSAR:OnAfterPilotUnloaded(From, Event, To, Helo, OpsGroup) |
On after "PilotUnloaded" event. |
|
[User] Switch sound output on and use normale (DCS) radio |
|
|
[User] Set default helo altitudeAGL. |
|
|
[User] Set default helo speed. |
|
|
[User] Set SRS TTS Voice of the rescue operator. |
|
|
[User] Set SRS TTS Voice of downed pilot. |
|
AICSAR:SetSRSRadio(OnOff, Path, Frequency, Modulation, SoundPath, Port) |
[User] Switch sound output on and use SRS output for sound files. |
|
[User] Switch sound output on and use SRS-TTS output. |
|
|
Default speed setting for the helicopter FLIGHTGROUP is 100kn. |
|
|
Triggers the FSM event "Status". |
|
|
Triggers the FSM event "Stop". |
|
|
In case Event LandingAfterEjection isn't working, use set this to true. |
|
|
[Internal] Check helo queue |
|
|
[Internal] Check if pilot arrived in rescue zone (MASH) |
|
|
[Internal] Check pilot queue for next mission |
|
|
[Internal] Count helos queue |
|
|
[Internal] Spawn a pilot |
|
|
[Internal] Catch the ejection and save the pilot name |
|
|
[Internal] Catch the landing after ejection and spawn a pilot in situ. |
|
|
[Internal] Get FlightGroup |
|
|
[Internal] Create a new rescue mission |
|
|
Triggers the FSM event "Status" after a delay. |
|
|
Triggers the FSM event "Stop" after a delay. |
|
|
Alias Name. |
|
|
Only send a helo when no human heli pilots are available. |
|
|
Colition side. |
|
|
FARP object from where to start. |
|
|
MASH zone to drop rescued pilots. |
|
|
number of helos available (default: 3) |
|
|
Table of Ops.FlightGroup#FLIGHTGROUP objects |
|
|
Template for CSAR helo. |
|
|
LID for log entries. |
|
|
limit available number of helos going on mission (defaults to true) |
|
|
Max distance to go for a rescue. |
|
|
[Internal] onafterHeloDown |
|
AICSAR:onafterPilotDown(From, Event, To, Coordinate, InReach) |
[Internal] onafterPilotDown |
|
[Internal] onafterPilotKIA |
|
AICSAR:onafterPilotPickedUp(From, Event, To, Helo, CargoTable, Index) |
[Internal] onafterPilotPickedUp |
|
[Internal] onafterPilotRescued |
|
AICSAR:onafterPilotUnloaded(From, Event, To, Helo, OpsGroup) |
[Internal] onafterPilotUnloaded |
|
[Internal] onafterStart |
|
|
[Internal] onafterStatus |
|
|
[Internal] onafterStop |
|
|
Table index to bind pilot to helo. |
|
|
Queue of pilots to rescue. |
|
|
Track if alive heli pilots are available. |
|
|
Track number of rescued pilot. |
|
|
Radius around downed pilot for the helo to land in. |
|
|
Template for pilot. |
|
|
Switch more output. |
|
|
Versioning. |
| Fields and Methods inherited from FSM | Description |
|---|---|
|
Adds an End state. |
|
|
Set the default #FSM_PROCESS template with key ProcessName providing the ProcessClass and the process object when it is assigned to a Wrapper.Controllable by the task. |
|
|
Adds a score for the FSM to be achieved. |
|
AICSAR:AddScoreProcess(From, Event, State, ScoreText, Score) |
Adds a score for the FSM_PROCESS to be achieved. |
|
Add a new transition rule to the FSM. |
|
|
Get current state. |
|
|
Returns the End states. |
|
|
Returns a table of the SubFSM rules defined within the FSM. |
|
|
Returns a table with the scores defined. |
|
|
Returns the start state of the FSM. |
|
|
Get current state. |
|
|
Returns a table with the Subs defined. |
|
|
Returns a table of the transition rules defined within the FSM. |
|
|
Check if FSM is in state. |
|
|
Load call backs. |
|
|
Creates a new FSM object. |
|
|
Sets the start state of the FSM. |
|
|
Add to map. |
|
|
Call handler. |
|
|
Create transition. |
|
|
Delayed transition. |
|
|
Event map. |
|
|
Go sub. |
|
|
Handler. |
|
|
Is end state. |
|
|
Sub maps. |
|
|
Check if can do an event. |
|
|
Check if cannot do an event. |
|
|
Check if FSM is in state. |
|
AI CSAR class.
Field(s)
Default altitude setting for the helicopter FLIGHTGROUP 1500ft.
Name of this class.
In case of UseEventEject wait this long until we spawn a landed pilot.
TODO Messages - Messages enum @field Messages
TODO Radio Messages - Radio Messages enum for ogg files length in secs @field RadioLength
TODO Radio Messages - Radio Messages enum for ogg files @field RadioMessages
Default speed setting for the helicopter FLIGHTGROUP is 100kn.
In case Event LandingAfterEjection isn't working, use set this to true.
Alias Name.
Only send a helo when no human heli pilots are available.
Colition side.
English standard localization
number of helos available (default: 3)
Table of Ops.FlightGroup#FLIGHTGROUP objects
Template for CSAR helo.
LID for log entries.
limit available number of helos going on mission (defaults to true)
Max distance to go for a rescue.
Table index to bind pilot to helo.
Queue of pilots to rescue.
Track number of rescued pilot.
Radius around downed pilot for the helo to land in.
Template for pilot.
Switch more output.
Versioning.
Function(s)
[Internal] Sound output via non-SRS Radio.
Add message files (.ogg) via "Sound to..." in the ME.
Defined in:
AICSAR
Parameters:
#string Soundfile
Name of the soundfile
#number Duration
Duration of the sound
#string Subtitle
Text to display
Return value:
self
[Internal] Create the Moose TextAndSoundEntries
Function to create a new AICSAR object
Defined in:
AICSAR
Parameters:
#string Alias
Name of this instance.
#number Coalition
Coalition as in coalition.side.BLUE, can also be passed as "blue", "red" or "neutral"
#string Pilottemplate
Pilot template name.
#string Helotemplate
Helicopter template name.
FARP object or Airbase from where to start.
Core.Zone#ZONE MASHZone
Zone where to drop pilots after rescue.
Return value:
self
On after "HeloDown" event.
Defined in:
AICSAR
Parameters:
#string From
From state.
#string Event
Event.
#string To
To state.
#number Index
On after "HeloOnDuty" event.
Defined in:
AICSAR
Parameters:
#string From
From state.
#string Event
Event.
#string To
To state.
Wrapper.Group#GROUP Helo
Helo group object
On after "PilotDown" event.
Defined in:
AICSAR
Parameters:
#string From
From state.
#string Event
Event.
#string To
To state.
Core.Point#COORDINATE Coordinate
Location of the pilot.
#boolean InReach
True if in maxdistance else false.
On after "PilotKIA" event.
Defined in:
AICSAR
Parameters:
#string From
From state.
#string Event
Event.
#string To
To state.
On after "PilotPickedUp" event.
Defined in:
AICSAR
Parameters:
#string From
From state.
#string Event
Event.
#string To
To state.
#table CargoTable
of Ops.OpsGroup#OPSGROUP Cargo objects
#number Index
On after "PilotRescued" event.
Defined in:
AICSAR
Parameters:
#string From
From state.
#string Event
Event.
#string To
To state.
#string PilotName
On after "PilotUnloaded" event.
Defined in:
AICSAR
Parameters:
#string From
From state.
#string Event
Event.
#string To
To state.
Ops.OpsGroup#OPSGROUP OpsGroup
[User] Switch sound output on and use normale (DCS) radio
Defined in:
AICSAR
Parameters:
#boolean OnOff
Switch on (true) or off (false).
#number Frequency
Defaults to 243 (guard).
#number Modulation
Radio modulation. Defaults to radio.modulation.AM.
Wrapper.Group#GROUP Group
The group to use as sending station.
Return value:
self
[User] Set default helo altitudeAGL.
Note - AI might have other ideas. Defaults to 1500ft.
[User] Set default helo speed.
Note - AI might have other ideas. Defaults to 100kn.
[User] Set SRS TTS Voice of the rescue operator.
AICSAR:SetSRSTTSRadio() needs to be set first!
Defined in:
AICSAR
Parameters:
#string Voice
The voice to be used, e.g. MSRS.Voices.Google.Standard.en_US_Standard_J for Google or MSRS.Voices.Microsoft.David for Microsoft.
Specific voices override culture and gender!
#string Culture
(Optional) The culture to be used, defaults to "en-GB"
#string Gender
(Optional) The gender to be used, defaults to "female"
Return value:
self
[User] Set SRS TTS Voice of downed pilot.
AICSAR:SetSRSTTSRadio() needs to be set first!
Defined in:
AICSAR
Parameters:
#string Voice
The voice to be used, e.g. MSRS.Voices.Google.Standard.en_US_Standard_J for Google or MSRS.Voices.Microsoft.David for Microsoft.
Specific voices override culture and gender!
#string Culture
(Optional) The culture to be used, defaults to "en-US"
#string Gender
(Optional) The gender to be used, defaults to "male"
Return value:
self
[User] Switch sound output on and use SRS output for sound files.
Defined in:
AICSAR
Parameters:
#boolean OnOff
Switch on (true) or off (false).
#string Path
Path to your SRS Server Component, e.g. "C:\\Program Files\\DCS-SimpleRadio-Standalone"
#number Frequency
Defaults to 243 (guard)
#number Modulation
Radio modulation. Defaults to radio.modulation.AM
#string SoundPath
Where to find the audio files. Defaults to nil, i.e. add messages via "Sound to..." in the Mission Editor.
#number Port
Port of the SRS, defaults to 5002.
Return value:
self
[User] Switch sound output on and use SRS-TTS output.
The voice will be used across all outputs, unless you define an extra voice for downed pilots and/or the operator.
See AICSAR:SetPilotTTSVoice() and AICSAR:SetOperatorTTSVoice()
Defined in:
AICSAR
Parameters:
#boolean OnOff
Switch on (true) or off (false).
#string Path
Path to your SRS Server Component, e.g. "E:\\Program Files\\DCS-SimpleRadio-Standalone"
#number Frequency
(Optional) Defaults to 243 (guard)
#number Modulation
(Optional) Radio modulation. Defaults to radio.modulation.AM
#number Port
(Optional) Port of the SRS, defaults to 5002.
#string Voice
(Optional) The voice to be used.
#string Culture
(Optional) The culture to be used, defaults to "en-GB"
#string Gender
(Optional) The gender to be used, defaults to "male"
#string GoogleCredentials
(Optional) Path to google credentials
Return value:
self
[Internal] Check if pilot arrived in rescue zone (MASH)
Defined in:
AICSAR
Parameter:
Wrapper.Group#GROUP Pilot
The pilot to be rescued.
Return value:
#boolean:
outcome
[Internal] Check pilot queue for next mission
[Internal] Count helos queue
Defined in:
AICSAR
Return value:
#number:
Number of helos on mission
[Internal] Spawn a pilot
Defined in:
AICSAR
Parameters:
Core.Point#COORDINATE _LandingPos
Landing Postion
#number _coalition
Coalition side
Return value:
self
[Internal] Catch the ejection and save the pilot name
[Internal] Catch the landing after ejection and spawn a pilot in situ.
[Internal] Get FlightGroup
[Internal] Create a new rescue mission
Defined in:
AICSAR
Parameters:
Wrapper.Group#GROUP Pilot
The pilot to be rescued.
#number Index
Index number of this pilot
Return value:
self
Triggers the FSM event "Status" after a delay.
Defined in:
AICSAR
Parameter:
#number delay
Delay in seconds.
Triggers the FSM event "Stop" after a delay.
Defined in:
AICSAR
Parameter:
#number delay
Delay in seconds.
[Internal] onafterHeloDown
Defined in:
AICSAR
Parameters:
#string From
#string Event
#string To
#number Index
Return value:
self
[Internal] onafterPilotDown
Defined in:
AICSAR
Parameters:
#string From
#string Event
#string To
Core.Point#COORDINATE Coordinate
Location of the pilot.
#boolean InReach
True if in maxdistance else false.
Return value:
self
[Internal] onafterPilotKIA
[Internal] onafterPilotPickedUp
Defined in:
AICSAR
Parameters:
#string From
#string Event
#string To
#table CargoTable
of Ops.OpsGroup#OPSGROUP Cargo objects
#number Index
Return value:
self
[Internal] onafterPilotRescued
Defined in:
AICSAR
Parameters:
#string From
#string Event
#string To
#string PilotName
Return value:
self
[Internal] onafterPilotUnloaded
Defined in:
AICSAR
Parameters:
#string From
#string Event
#string To
Ops.OpsGroup#OPSGROUP OpsGroup
Return value:
self
[Internal] onafterStart
[Internal] onafterStatus
[Internal] onafterStop
Field(s)
Default altitude setting for the helicopter FLIGHTGROUP 1500ft.
Name of this class.
In case of UseEventEject wait this long until we spawn a landed pilot.
TODO Messages - Messages enum @field Messages
TODO Radio Messages - Radio Messages enum for ogg files length in secs @field RadioLength
TODO Radio Messages - Radio Messages enum for ogg files @field RadioMessages
Default speed setting for the helicopter FLIGHTGROUP is 100kn.
In case Event LandingAfterEjection isn't working, use set this to true.
Alias Name.
Only send a helo when no human heli pilots are available.
Colition side.
English standard localization
number of helos available (default: 3)
Table of Ops.FlightGroup#FLIGHTGROUP objects
Template for CSAR helo.
LID for log entries.
limit available number of helos going on mission (defaults to true)
Max distance to go for a rescue.
Table index to bind pilot to helo.
Queue of pilots to rescue.
Track number of rescued pilot.
Radius around downed pilot for the helo to land in.
Template for pilot.
Switch more output.
Versioning.
Function(s)
Adds an End state.
Set the default #FSM_PROCESS template with key ProcessName providing the ProcessClass and the process object when it is assigned to a Wrapper.Controllable by the task.
Defined in:
Parameters:
#table From
Can contain a string indicating the From state or a table of strings containing multiple From states.
#string Event
The Event name.
Core.Fsm#FSM_PROCESS Process
An sub-process FSM.
#table ReturnEvents
A table indicating for which returned events of the SubFSM which Event must be triggered in the FSM.
Return value:
The SubFSM.
Adds a score for the FSM to be achieved.
Defined in:
Parameters:
#string State
is the state of the process when the score needs to be given. (See the relevant state descriptions of the process).
#string ScoreText
is a text describing the score that is given according the status.
#number Score
is a number providing the score of the status.
Return value:
#FSM:
self
Adds a score for the FSM_PROCESS to be achieved.
Defined in:
Parameters:
#string From
is the From State of the main process.
#string Event
is the Event of the main process.
#string State
is the state of the process when the score needs to be given. (See the relevant state descriptions of the process).
#string ScoreText
is a text describing the score that is given according the status.
#number Score
is a number providing the score of the status.
Return value:
#FSM:
self
Add a new transition rule to the FSM.
A transition rule defines when and if the FSM can transition from a state towards another state upon a triggered event.
Defined in:
Parameters:
#table From
Can contain a string indicating the From state or a table of strings containing multiple From states.
#string Event
The Event name.
#string To
The To state.
Get current state.
Returns the End states.
Returns a table of the SubFSM rules defined within the FSM.
Returns a table with the scores defined.
Returns the start state of the FSM.
Get current state.
Returns a table with the Subs defined.
Returns a table of the transition rules defined within the FSM.
Check if FSM is in state.
Defined in:
Parameter:
#string State
State name.
Return value:
#boolean:
If true, FSM is in this state.
Load call backs.
Sets the start state of the FSM.
Add to map.
Call handler.
Defined in:
Parameters:
#string step
Step "onafter", "onbefore", "onenter", "onleave".
#string trigger
Trigger.
#table params
Parameters.
#string EventName
Event name.
Return value:
Value.
Create transition.
Defined in:
Parameter:
#string EventName
Event name.
Return value:
#function:
Function.
Delayed transition.
Defined in:
Parameter:
#string EventName
Event name.
Return value:
#function:
Function.
Event map.
Go sub.
Defined in:
Parameters:
#string ParentFrom
Parent from state.
#string ParentEvent
Parent event name.
Return value:
#table:
Subs.
Handler.
Is end state.
Defined in:
Parameter:
#string Current
Current state name.
Return values:
#table:
FSM parent.
#string:
Event name.
Sub maps.
Check if can do an event.
Defined in:
Parameter:
#string e
Event name.
Return values:
#boolean:
If true, FSM can do the event.
#string:
To state.
Check if cannot do an event.
Defined in:
Parameter:
#string e
Event name.
Return value:
#boolean:
If true, FSM cannot do the event.
Check if FSM is in state.
Defined in:
Parameters:
#string State
State name.
state
Return value:
#boolean:
If true, FSM is in this state.