/********* pook_ARTY Artillery Fire Mission Function *********************************************************************

Initiates player-requested artillery fire mission for friendly AI-controlled arty units. This can be scripted for
mission-driven artillery support fire missions by "real" units on the map. The use of in-mission active AI
artillery units makes the counter-artillery strike mission a real possibility. Enemy guns can be eliminated;
friendly artillery has the potential to be destroyed. Consider a scripted mission with enemy AI calling in
artillery strikes and you and your SF squad is tasked with finding and neutralizing the artillery units!

The function can be assigned to a forward observer, spotter, or other "control" unit, and enemy artillery may
become active by careful use of triggers or condition scripts to dynamically change mission parameters.

All these possibilities exist due to "real" units on the map making use of this function, which turns artillery
into a dynamic aspect for any SP or MP mission!

This function currently supports:
- POOK_ARTY: 2S19, 2S1, 2S3, 2S5, A-222, 9K58, TOS-1A
- POOK_AFV: Pandur M-121 Mortar carrier
- CUP: M270, BM-21, M1129 mortar carrier, 2B14 mortar, D30, M119
- VME_PLA: PLZ-05, PLZ-07, PL-96 (aka Type 86 - D30 copy), PP87 mortar, PHZ-10, PHZ-81, PHL-03, PLL-05
- RHS: M119, D30, M109, 2S3, M252 mortar, 2B14 mortar, BM-21, M142 (HIMARS)
- BIS vanilla artillery

SRBM and SCUD fire missions are provided in their respective functions contained in the pook_Arty pack.

Please comment in the BIS forum topic if other units should be considered for addition to this list.

Author: hcpookie

Arguments:
==========
0: The player calling the mission
1: TYPE: The artillery ammo type being requested (default = "HE")
"HE", "SMOKE", "ILLUM", and "CBU" types are available.
2: OPTIONAL: Range (in km) to check for friendly launchers (default = 20km)
3: OPTIONAL: Map grid coordinates. Uses standard coordinate format (ex. [0,0,0]).

USAGE:
======
1. Place an AI artillery unit via editor, or spawn within mission.

2. Add the function to any forward observer, fire controller, recon vehicle, specops radio, etc. depending on your
mission needs. The Fire Controller should be a Commander/Spotter/Radio operator, etc. or a forward observer
vehicle operator. The controller could even be a scout plane, helicopter, etc. that would be in a position
to request the artillery missions.

The controller assignment is added either via "addAction" or via a trigger/script to assign the desired ammo
type to an Artillery Fire Controller.

Note that the ammo type values are CASE-SENSITIVE! Supported types are: "HE","SMOKE","ILLUM","CBU". The
function will default to "HE" if no value is passed:

this addAction ["Arty Mission", {[player] spawn pook_ARTY_FNC_ARTYMISSION},"",1,false,true];
- or -
_arty = [this] spawn pook_ARTY_FNC_ARTYMISSION;


----
HE:
----
Using the HE value will launch a conventional high explosive arty fire mission. You may replace "player" with
the object's "Variable Name" (in the editor) depending on your scripting needs:

this addAction ["Arty Mission", {[player, "HE", 20] spawn pook_ARTY_FNC_ARTYMISSION},"",1,false,true];


ALTERNATIVE USAGE: You may also use a trigger/script in place of the artillery controller:

_arty = [this, "HE"] spawn pook_ARTY_FNC_ARTYMISSION;



-------
SMOKE:
-------
Using the SMOKE value will launch a covering smoke barrage fire mission. You may replace "player" with
the object's "Variable Name" (in the editor) depending on your scripting needs:

this addAction ["Arty Mission", {[player, "SMOKE", 20] spawn pook_ARTY_FNC_ARTYMISSION},"",1,false,true];


ALTERNATIVE USAGE: You may also use a trigger/script in place of the artillery controller:

_arty = [this, "SMOKE"] spawn pook_ARTY_FNC_ARTYMISSION;



-------
ILLUM:
-------
Using the ILLUM value will launch a flare illumination fire mission. You may replace "player" with
the object's "Variable Name" (in the editor) depending on your scripting needs:

this addAction ["Arty Mission", {[player, "ILLUM", 20] spawn pook_ARTY_FNC_ARTYMISSION},"",1,false,true];


ALTERNATIVE USAGE: You may also use a trigger/script in place of the artillery controller:

_arty = [this, "ILLUM"] spawn pook_ARTY_FNC_ARTYMISSION;



-----
CBU:
-----
Using the CBU value will launch a cluster munition fire mission. You may replace "player" with the
object's "Variable Name" (in the editor) depending on your scripting needs:

this addAction ["Arty Mission", {[player, "CBU", 20] spawn pook_ARTY_FNC_ARTYMISSION},"",1,false,true];


ALTERNATIVE USAGE: You may also use a trigger/script in place of the artillery controller:

_arty = [this, "CBU"] spawn pook_ARTY_FNC_ARTYMISSION;



3. OPTIONAL: The third input parameter defines the search radius to seek friendly AI artillery units.
Default search is 20km. This can be adjusted to accommodate multiple forward observers in the same mission.

Example - to narrow the search for friendly units to 4km, change the input as follows:

this addAction ["Arty Mission", {[player, "HE", 4] spawn pook_ARTY_FNC_ARTYMISSION},"",1,false,true];
- or -
_arty = [this,"HE",4] spawn pook_ARTY_FNC_ARTYMISSION;


4. OPTIONAL: Map grid Coordinates. Uses standard coordinate format (ex. [0,0,0]). May be used for scripting
purposes. If no value is passed, the fire mission operator will prompted for map-click coordinates.

Example - to create a fire mission for a fixed position such as an enemy camp at map grid 150256, change
the input as follows:

this addAction ["Arty Mission", {[player, "HE",,[150,256,0]] spawn pook_ARTY_FNC_ARTYMISSION},"",1,false,true];
- or -
_arty = [this,"HE",,[150,256,0]] spawn pook_ARTY_FNC_ARTYMISSION;


5. Once the inputs are provided, the function will only select artillery units that meet the following criteria:
- Only AI units are considered
- Stationary - vehicles that are moving or in transit (either in a convoy or being airlifted) are ignored
- Friendly AI units on the side (will not select neutral units)
- Units in range of fire mission coordinates
- Units with available ammo for the selected type of fire mission
- Only alive units are selected; if the unit is destroyed, dead, or captured, the unit will not be tasked

6. The AI gunner will first fire a spotter smoke round, and within 45 seconds all units within the battery will
begin the main artillery barrage.

7. Each AI unit will fire a random amount of artillery, anywhere between 3-8 rounds.

8. If AI is in a group, all similar units in that group will fire a salvo. Different artillery types in the same
group may not participate in the fire mission.



RETURN:
=======
- AI will send sideRadio and sideChat notices confirming fire mission or reporting status if
out of ammo, or no friendly artillery units are in the area (default 20km zone).

NOTES:
======
- Cannot be used for human-controlled artillery units.
- Fire Mission command cannot be aborted!
- The artillery in the pook_Arty mod is calibrated to Real World values, and can launch
anywhere between 1-40km depending on specific unit's capabilities.
- Time on Target may vary greatly depending on distance, AI skill, and the specific arty unit's reload
times (which are adjusted to Real World values in the pook_Arty pack).

*************************************************************************************************************************/