DMS_fnc_AddMissionToMonitor

Author: eraser1

General information: This function parses and adds mission information to "DMS_Mission_Arr" for Mission Monitoring. Then it will return true if the info was added successfully, false otherwise.

Usage:

[
	_position,
	[
		[
			_completionType1,
			_completionArgs1,
			_isAbsoluteCondition
		],
		[
			_completionType2,
			_completionArgs3,
			_isAbsoluteCondition
		],
		...
		[
			_completionTypeN,
			_completionArgsN,
			_isAbsoluteCondition
		],
	],
	[
		_timeStarted,
		_timeUntilFail
	],
	[
		_AIUnitOrGroup1,
		_AIUnitOrGroup2,
		...,
		_AIUnitOrGroupN
	],
	[
		[_cleanupObj1,_cleanupObj2,...,_cleanupObjN],
		[_vehicle1,_vehicle2,...,_vehicleN],
		[
			[_crate1,_crate_loot_values1],
			[_crate2,_crate_loot_values2]
		]
	],
	[_missionName,_msgWIN,_msgLose],
	_markers,
	_side,
	_difficulty,
	_missionEvents,
	[
		_onSuccessScript,			// (OPTIONAL) Array of code or string to be executed on mission completion (in addition to regular code). Each element should be an array in the form [_params, _code].
		_onFailScript,				// (OPTIONAL) Array of code or string to be executed on mission failure (in addition to regular code). Each element should be an array in the form [_params, _code].
		_onMonitorStart,			// (OPTIONAL) Code to run when the monitor starts to check the mission status. The passed parameter (_this) is the mission data array itself.
		_onMonitorEnd				// (OPTIONAL) Code to run when the monitor is done with checking the mission status. The passed parameter (_this) is the mission data array itself.
	]
] call DMS_fnc_AddMissionToMonitor;

Parameters:

_position < ARRAY > is the location of the mission (in positionATL).

_completionTypeX < STRING >, _completionArgsX < ANY >, and _isAbsoluteCondition < BOOLEAN > describe mission completion requirements. See "DMS_fnc_MissionSuccessState" for more info.

_timeStarted < NUMBER > is the time (in diag_tickTime) that the mission started. This value can be nil and the function will automatically use the current time.

_timeUntilFail < NUMBER > is how much time (in seconds) it takes for the mission to fail. As with _timeStarted, this can be left nil and the function will automatically choose a time based off of DMS_MissionTimeOut config values.

_AIUnitOrGroupX < OBJECT > or < GROUP > defines an AI unit or a group that has been spawned to this mission. These units are used for showing on the map the # of remaining AI (if enabled to do so in the config).

_cleanupObjX < OBJECT > defines an object that should be cleaned up when the mission ends. Any props/buildings spawned for the mission should be listed here.

_vehicleX < OBJECT > defines a mission reward vehicle. These vehicles are locked and invincible until the mission completes, when it will either be unlocked if the mission is successful, or deleted otherwise.

_crateX < OBJECT > and _crate_loot_values1 < ANY > respectively define the crate object and the loot to spawn inside of it. Keep in mind that the "crate" object doesn't have to be an actual crate; it can also be a vehicle, or anything else that can hold gear. See "DMS_fnc_FillCrate" for more info.

_missionName < STRING > defines the "name" of the mission. eg: "Armed Bandits", "Mercenary Group", "Construction Site", etc. It is also the title of any mission related messages broadcasted to players.

_msgWIN < STRING > defines the message that is broadcasted to all players when the mission is completed (successfully).

_msgLose < STRING > defines the message that is broadcasted to all players when the mission fails.

_markers < ARRAY > defines the map marker(s) for the mission. These are included so that they can be deleted when the mission is over.

_side < STRING > defines the "side" of the AI in the mission. EG "bandit"/"hero" etc.

_difficulty < STRING > defines the difficulty of the mission. Default difficulties are: "easy", "moderate", "difficult", and "hardcore".

_missionEvents < ARRAY > currently unused.

OPTIONAL PARAMETERS:

_onSuccessScript < ARRAY > is a two part array defined as [_params, _code]. The variable _params is passed to a function defined as _code, which is run if/when the mission is completed successfully. Default: []

_onFailScripts < ARRAY > is a two part array defined as [_params, _code]. The variable _params is passed to a function defined as _code, which is run if/when the mission fails. Default: []

_onMonitorStart < CODE > defines the script/code to run before the monitor checks the mission status. Default: {}

_onMonitorEnd < CODE > defines the script/code to run AFTER the monitor checks the mission status. Default: {}

Keep in mind that if you want to define any of the above 4 optional parameters, it must be defined inside of an array that contains each of the 4 parameters.

Example (from the "Armed Bandits" mission):

_added =
[
	_pos,
	[
		[
			"kill",
			_group
		],
		[
			"playerNear",
			[_pos,DMS_playerNearRadius]
		]
	],
	[
		_time,
		(DMS_MissionTimeOut select 0) + random((DMS_MissionTimeOut select 1) - (DMS_MissionTimeOut select 0))
	],
	_missionAIUnits,
	_missionObjs,
	[_missionName,_msgWIN,_msgLOSE],
	_markers,
	_side,
	_difficulty,
	[]
] call DMS_fnc_AddMissionToMonitor;