Revision as of 20:51, 6 June 2020

Twitter: http://twitter.com/Killzone_Kid

Youtube: http://www.youtube.com/killzonekidtv

Often Used Links

Arma 3 Event Handlers (before the edit with examples)

Introduction

An event handler (abbreviated to EH) allows you to automatically monitor and then execute custom code upon particular events being triggered.

These event handlers relate to commands such as: addEventHandler, removeEventHandler, removeAllEventHandlers.

General MP Note

As opposed to OFP event handlers, a respawned unit retains the EHs it had before, so it is no longer required to re-add EHs after respawning.

The MP event handlers "MPHit", "MPKilled" and "MPRespawn" have to be assigned to the object by using addMPEventHandler.

Event Scripts

See also: Event Scripts for special event triggered scripts.

Event Handler List

AnimChanged

Triggered every time a new animation is started. It can be assigned to a remote unit but will only fire on the PC where the actual addEventHandler command was executed.

Passed array: [unit, anim]

unit: Object - Object the event handler is assigned to
anim: String - Name of the anim that is started

AnimDone

Triggered every time an animation is finished. It can be assigned to a remote unit but will only fire on the PC where the actual addEventHandler command was executed.

Passed array: [unit, anim]

unit: Object - Object the event handler is assigned to
anim: String - Name of the anim that has been finished

AnimStateChanged

Triggered every time an animation state changes. Unlike AnimChanged and AnimDone, it is triggered for all animation states in a sequence. It can be assigned to a remote unit but will only fire on the PC where the actual addEventHandler command was executed.

Passed array: [unit, anim]

unit: Object - Object the event handler is assigned to
anim: String - Name of the anim that has been started

ControlsShifted

Triggers when controls of vehicle are shifted (pilot->co-pilot, co-pilot->pilot). Works for both, "Take" and "Release" controls actions. Event only triggers on PC where vehicle is local and EH was added.

NOTE: If helicopter is local to the server and co-pilot takes controls, the helicopter changes locality to co-pilot PC. This means that if "ControlsShifted" EH was added on both server and client, "Take Controls" action will trigger EH on the server PC, but subsequent co-pilot "Release Controls" action will trigger it on co-pilot's PC.

Passed array: [vehicle, newController, oldController]

vehicle: Object - Vehicle which controls were shifted.
newController: Object - Unit who controls vehicle after this event.
oldController: Object - Unit who controled vehicle before this event.

Dammaged

Triggered when the unit is damaged. In ArmA works with all vehicles not only men like in OFP. It can be assigned to a remote vehicle but will only fire on the PC where the actual addEventHandler command was executed.

(If simultaneous damage occured (e.g. via grenade) EH might be triggered several times.)

Passed array: [unit, selectionName, damage]

unit: Object - Object the event handler is assigned to
selectionName: String - Name of the selection where the unit was damaged
damage: Number - Resulting level of damage

Engine

Triggered when the engine of the unit is turned on/off.

Global.

Passed array: [vehicle, engineState]

vehicle: Object - Vehicle the event handler is assigned to
engineState: Boolean - True when the engine is turned on, false when turned off

EpeContact

Triggered when object collision (PhysX) is in progress. It can be assigned to a remote vehicle but will only fire on the PC where the actual addEventHandler command was executed.

Passed array: [object1, object2, select1, select2, force]

object1: Object - Object with attached handler.
object2: Object - Object which is colliding with object1.
select1: String - Selection of object1 which is colliding - not in use at this moment, empty string is always returned.
select2: String - Selection of object2 which is colliding - not in use at this moment, empty string is always returned.
force: Number - Force of collision.

EpeContactEnd

Triggered when object collision (PhysX) ends. It can be assigned to a remote vehicle but will only fire on the PC where the actual addEventHandler command was executed.

Passed array: [object1, object2, select1, select2, force]

object1: Object - Object with attached handler.
object2: Object - Object which is colliding with object1.
select1: String - Selection of object1 which is colliding - not in use at this moment, empty string is always returned.
select2: String - Selection of object2 which is colliding - not in use at this moment, empty string is always returned.
force: Number - Force of collision.

EpeContactStart

Triggered when object collision (PhysX) starts. It can be assigned to a remote vehicle but will only fire on the PC where the actual addEventHandler command was executed.

Passed array: [object1, object2, select1, select2, force]

object1: Object - Object with attached handler.
object2: Object - Object which is colliding with object1.
select1: String - Selection of object1 which is colliding - not in use at this moment, empty string is always returned.
select2: String - Selection of object2 which is colliding - not in use at this moment, empty string is always returned.
force: Number - Force of collision.

Explosion

Triggered when a vehicle or unit is damaged by a nearby explosion. It can be assigned to a remote vehicle but will only fire on the PC where the actual addEventHandler command was executed.

Passed array: [vehicle, damage]

vehicle: Object - Object the event handler is assigned to
damage: Number - Damage inflicted to the object

Fired

Triggered when the unit fires a weapon.
This EH will not trigger if a unit fires out of a vehicle. For those cases an EH has to be attached to that particular vehicle.

Global.

Passed array: [unit, weapon, muzzle, mode, ammo]
OA b1.54.73642 : [unit, weapon, muzzle, mode, ammo, magazine, projectile]

unit: Object - Object the event handler is assigned to
weapon: String - Fired weapon
muzzle: String - Muzzle that was used
mode: String - Current mode of the fired weapon
ammo: String - Ammo used
magazine: String - magazine name which was used
projectile: Object - Object of the projectile that was shot

FiredNear

Triggered when a weapon is fired somewhere near the unit or vehicle.
It is also triggered if the unit itself is firing.

Global.

(Exception(s): the Throw weapon wont broadcast the FiredNear event)

Passed array: [unit, firer, distance, weapon, muzzle, mode, ammo]

unit: Object - Object the event handler is assigned to
firer: Object - Object which fires a weapon near the unit
distance: Number - Distance in meters between the unit and firer (max. distance ~69m)
weapon: String - Fired weapon
muzzle: String - Muzzle that was used
mode: String - Current mode of the fired weapon
ammo: String - Ammo used

Fuel

Triggered when the unit's fuel status changes between completely empty / not empty (only useful if the event handler is assigned to a vehicle).

Global.

Passed array: [vehicle, fuelState]

vehicle: Object - Vehicle the event handler is assigned to
fuelState: Boolean - 0 when no fuel, 1 when the fuel tank is full

Gear

Triggered when the unit lowers/retracts the landing gear (only useful if the event handler is assigned to is a member of the class "Plane").

Global. Passed array: [vehicle, gearState]

vehicle: Object - Vehicle the event handler is assigned to
gearState: Boolean - True when the gear is lowered, false when retracted

GetIn

Triggers when a unit enters a vehicle. It can be assigned to a remote vehicle but will only fire on the PC where the actual addEventHandler command was executed. This EH is neither triggered upon a change of positions within the same vehicle nor by the moveInXXXX commands. However it is triggered by a "GetInXXXX" action.

Passed array: [vehicle, position, unit]

vehicle: Object - Vehicle the event handler is assigned to
position: String - Can be either "driver", "gunner", "commander" or "cargo"
unit: Object - Unit that entered the vehicle

In vehicles with multi-turret setup, entering any turret will show "gunner" for position. You can get the actual turret information from the unit itself: _heli addEventHandler ["GetIn", { hint str assignedVehicleRole (_this select 2); }];

GetOut

Triggers when a unit gets out from a vehicle. It can be assigned to a remote vehicle but will only fire on the PC where the actual addEventHandler command was executed. This EH is triggered by both the moveOut command and by "GetOut" action.

Passed array: [vehicle, position, unit]

vehicle: Object - Vehicle the event handler is assigned to
position: String - Can be either "driver", "gunner", "commander" or "cargo"
unit: Object - Unit that left the vehicle

In vehicles with multi-turret setup, exiting any turret will show "gunner" for position. You can get the actual turret information from the unit itself: _heli addEventHandler ["GetOut", { hint str assignedVehicleRole (_this select 2); }];

HandleDamage

Triggers when the unit is damaged and fires for each damaged selection separately. Works with all vehicles. This EH can accept a remote unit as argument however it will only fire when the unit is local to the PC this event handler was added on. For example, you can add this event handler to one particular vehicle on every PC. When this vehicle gets hit, only EH on PC where the vehicle is currently local will fire.

If code provided returns a numeric value, this value will overwrite the default damage of given selection after processing. Return value of 0 will make the unit invulnerable if damage is not scripted in other ways (i.e using setDamage and/or setHit for additional damage handling). If no value is returned, the default damage processing will be done. This allows for safe stacking of this event handler. Only the return value of the last added "HandleDamage" EH is considered.

Passed array: [unit, selectionName, damage, source, projectile]

unit: Object - Object the event handler is assigned to.
selectionName: String - Name of the selection where the unit was damaged. "" for over-all structural damage, "?" for unknown selections.
damage: Number - Resulting level of damage for the selection.
source: Object - The source unit that caused the damage.
projectile: String - Classname of the projectile that caused inflicted the damage. ("" for unknown, such as falling damage.)

Examples:

This code makes Bob invulnerable: _eh = Bob addEventHandler ["HandleDamage", {hint "IMMA INVINCIBLED!"; 0}];

This code will log damage values without interfering with default damage processing: _eh = Bob addEventHandler ["HandleDamage", {diag_log format ["T=%1 : %2", time, _this];}];

When shooting Bob once in the torso and once in the head, .RPT shows:

"T=11692.9 : [B Alpha 2-2:1,"head",0.0179969,<NULL-object>,"B_65x39_Caseless"]"
"T=11692.9 : [B Alpha 2-2:1,"",0.850484,B Alpha 1-1:1 (KK),"B_65x39_Caseless"]"
"T=11692.9 : [B Alpha 2-2:1,"",0.850484,B Alpha 1-1:1 (KK),"B_65x39_Caseless"]"
"T=11692.9 : [B Alpha 2-2:1,"head",0.0179969,B Alpha 1-1:1 (KK),"B_65x39_Caseless"]"
"T=11692.9 : [B Alpha 2-2:1,"body",0.0939217,B Alpha 1-1:1 (KK),"B_65x39_Caseless"]"
"T=11692.9 : [B Alpha 2-2:1,"hands",0.109993,B Alpha 1-1:1 (KK),"B_65x39_Caseless"]"

"T=11694.8 : [B Alpha 2-2:1,"head",0.899007,<NULL-object>,"B_65x39_Caseless"]"
"T=11694.8 : [B Alpha 2-2:1,"",0.346781,B Alpha 1-1:1 (KK),"B_65x39_Caseless"]"
"T=11694.8 : [B Alpha 2-2:1,"",1.19727,B Alpha 1-1:1 (KK),"B_65x39_Caseless"]"
"T=11694.8 : [B Alpha 2-2:1,"head",0.899007,B Alpha 1-1:1 (KK),"B_65x39_Caseless"]"

Notes:

Each "HandleDamage" event shows the current damage from the damage source, NOT cumulative or the current "damage level" (health) of the target unit.
Multiple "HandleDamage" event handlers can be added to the same unit, however only the damage return value from the last added EH will be relayed to the game engine.
You can save the last event as timestamp (diag_tickTime) onto the unit, as well as the current health of the unit/its selections, with setVariable and query it on each "HandleDamage" event with getVariable to define a system how to handle the "HandleDamage" event.
"HandleDamage" will continue to trigger even if the unit is already dead.
"HandleDamage" is persistent. If you add it to the player object, it will continue to exist after player respawned.
"HandleDamage" can trigger "twice" per damage event. Once for direct damage, once for indirect damage (explosive damage). This can happen even in the same frame, but is unlikely:

// first HandleDamage event - direct damage by sabot hit onto an infantry unit
1081.55,[TargetUnit,"",6426.05,SourceUnit,"Sh_120_SABOT"]
1081.55,[TargetUnit,"head_hit",441.609,SourceUnit,"Sh_120_SABOT"]
1081.55,[TargetUnit,"body",333.333,SourceUnit,"Sh_120_SABOT"]
1081.55,[TargetUnit,"hands",533.333,SourceUnit,"Sh_120_SABOT"]
1081.55,[TargetUnit,"legs",533.333,SourceUnit,"Sh_120_SABOT"]

// second HandleDamage event - indirect damage by the impact - maybe force/friction applied to the unit body
1081.59,[TargetUnit,"",2.24228,TargetUnit,""]
1081.59,[TargetUnit,"head_hit",0.89672,TargetUnit,""]
1081.59,[TargetUnit,"body",3.3113,TargetUnit,""]
1081.59,[TargetUnit,"hands",3.74862,TargetUnit,""]
1081.59,[TargetUnit,"legs",10,TargetUnit,""]

Link to explanation Celery's explanation

HandleHeal

Triggered when unit starts to heal (player using heal action or AI heals after being ordered). Triggers only on PC where EH is added and unit is local. If code returns false, engine side healing follows. Return true if you handle healing in script, use AISFinishHeal to tell engine that script side healing is done. See also lifeState and setUnconscious commands.

Passed array: [unit, healer, healercanheal]

unit: Object
healer: Object
healercanheal: Boolean - true when healer is corpsman

Hit

Triggered when the unit is hit/damaged.

Is not always triggered when unit is killed by a hit.
Most of the time only the killed event handler is triggered when a unit dies from a hit.
The hit EH will not necessarily fire if only minor damage occurred (e.g. firing a bullet at a tank), even though the damage increased.
Does not fire when a unit is set to allowDamage false.

Local.

Passed array: [unit, causedBy, damage]

unit: Object - Object the event handler is assigned to
causedBy: Object - Object that caused the damage.
Contains the unit itself in case of collisions.
damage: Number - Level of damage caused by the hit

HitPart

Runs when the object, it was added to, gets injured/damaged. It returns the position and component that was hit on the object within a nested array, this is because the model may have more than selection name for the hit component.

While you can add "HitPart" handler to a remote unit, the respectful addEventHandler command must be executed on the shooter's PC and will only fire on shooter's PC as well. Additionally, if the unit gets damaged by any means other than shooter's shooting, "HitPart" will not fire. Because of this, this event handler is most suitable for when the shooter needs feedback on his shooting, such as target practicing or hitmarker creation.

Passed array: [[target, shooter, bullet, position, velocity, selection, ammo, direction, radius, surface, direct]]

target: Object - Object that got injured/damaged.
shooter: Object - Unit that inflicted the damage. If injured by a vehicle impact or a fall the target itself is returned, or, in case of explosions, the null object. In case of explosives that were planted by someone (e.g. satchel charges), that unit is returned.
bullet: Object - Object that was fired.
position: Position3D - Position the bullet impacted (ASL).
velocity: Vector3D - 3D speed at which bullet impacted.
selection: Array - Array of Strings with named selection of the object that were hit.
ammo: Array - Ammo info: [hit value, indirect hit value, indirect hit range, explosive damage, ammo class name] OR, if there is no shot object: [impulse value on object collided with,0,0,0]
direction: Vector3D - vector that is orthogonal (perpendicular) to the surface struck. For example, if a wall was hit, vector would be pointing out of the wall at a 90 degree angle.
radius: Number - Radius (size) of component hit.
surface: String - Surface type struck.
direct: Boolean - true if object was directly hit, false if it was hit by indirect/splash damage.

HitPart Sample output after DemoCharge explosion

Init

Triggered on mission start or when a vehicle is created on the fly using createVehicle.

Global.

Passed array: [unit]

unit: Object - Object the event handler is assigned to

IncomingMissile

Triggered when a guided missile locked on the target or unguided missile or rocket aimed by AI at the target was fired.

Global.

Passed array: [unit, ammo, whoFired]

unit: Object - Object the event handler is assigned to
ammo: String - Ammo type that was fired on the unit
whoFired: Object - Object that fired the weapon

InventoryOpened

Triggered when a player opens inventory.

Local.

Passed array: [unit, container]

unit: Object - Object the event handler is assigned to
container: String - linked container or weaponholder

Killed

Triggered when the unit is killed.

Local.

Passed array: [unit, killer]

unit: Object - Object the event handler is assigned to
killer: Object - Object that killed the unit
Contains the unit itself in case of collisions.

Be careful when the killer has been a vehicle. For most cases the reference of the vehicle is the same as the effectiveCommander, yet not always. For example:

_gunner setVariable ["Variable",true];
_killer getVariable "Variable" => <null>
(gunner (vehicle _killer)) getVariable "Variable" => true

And sample debug output:

_killer => B 1-2-F:2
(gunner (vehicle _killer)) => B 1-2-F:2
((gunner (vehicle _killer)) == _killer) => false

LandedTouchDown

Triggered when a plane (AI or player) touches the ground.

Local.

Passed array: [plane, airportID]

plane: Object - Object the event handler is assigned to
airportID: Number - ID of the airport (-1 for anything else).

LandedStopped

Triggered when an AI pilot would get out usually. Not executed for player.

Local.

Passed array: [plane, airportID]

plane: Object - Object the event handler is assigned to
airportID: Number - ID of the airport (-1 for anything else).

Local

Triggered when locality of object in MP is changed.

Passed array: [localUnit, local]

localUnit: Object - Unit for who is object local.
local: Boolean - If the object is local on given computer.

MPHit

Triggered when the unit is hit/damaged. EH can be added on any machine and EH code will trigger globally on every connected client and server. Add it only on server because if you have 10 machines on network and add this EH to every machine, when triggered the EH code will be executed 10 x 10 = 100 times.

Is not always triggered when unit is killed by a hit. Most of the time only the Killed event handler is triggered when a unit dies from a hit. The hit EH will not necessarily fire if only minor damage occurred (e.g. firing a bullet at a tank), even though the damage increased. Can also trigger several times for an explosion (direct and indirect damage). Does not fire when a unit is set to allowDamage false. However it will fire with "HandleDamage" EH added alongside stopping unit from taking damage addEventHandler ["HandleDamage",{0}]; Will not trigger when unit is dead.

This EH must be used in conjunction with the addMPEventHandler command.

Passed array: [unit, causedBy, damage]

unit: Object - Object the event handler is assigned to
causedBy: Object - Object that caused the damage. Contains the unit itself in case of collisions.
damage: Number - Level of damage caused by the hit

Coding advice:

Call a function from the MPHit EH code space, rather to define the full code in there directly. The reason is the code space will be transferred over network on each event activation - so keep the data as small as possible!

//good MyTag_Function = { //your code }; _unit addMPEventHandler ["MPHit", {_this call MyTag_Function}];

//bad _unit addMPEventHandler ["MPHit", { //your code }];

MPKilled

Triggered when the unit is killed. EH can be added on any machine and EH code will trigger globally on every connected client and server. Add it only on server because if you have 10 machines on network and add this EH to every machine, when triggered the EH code will be executed 10 x 10 = 100 times.

Passed array: [unit, killer]

unit: Object - Object the event handler is assigned to
killer: Object - Object that killed the unit
Contains the unit itself in case of collisions.

Notes:

This command must be used in conjunction with the command addMPEventHandler rather than the old command used for non MP commands.
This event handler is triggered for a disconnecting player, if "playableAI" are disabled (by admin or description.ext), so that the playable unit dies on disconnect.

Coding advice:

Call a function from the MPKilled EH code space, rather to define the full code in there directly. The reason is the code space will be transferred over network on each event activation - so keep the data as small as possible!

//good MyTag_Function = { //your code }; _unit addMPEventHandler ["MPKilled", {_this call MyTag_Function}];

//bad _unit addMPEventHandler ["MPKilled", { //your code }];

MPRespawn

Triggered when a unit respawns.

Global.

Passed array: [unit, corpse, ...]

unit: Object - Object the event handler is assigned to
corpse: Object - Object the event handler was assigned to, aka the corpse/unit player was previously controlling.

Notes:

This event never triggers on server: [1]

As of OA 1.62, this command does not work as one would expect. It is only triggered on the machine where the unit it was assigned to is local. The only difference between Respawn and MPRespawn is that MPRespawn can be assigned from anywhere while Respawn requires the unit to be local.

This command must be used in conjunction with the command addMPEventHandler rather than the old command used for non MP commands.

MusicStart

Triggers when CfgMusic sound starts playing, after being executed with playMusic command.

This event handler needs to be added with addMusicEventHandler command and removed with removeMusicEventHandler. Passed array: [className, handlerID]

className: String - CfgMusic class name of currently playing sound.
handlerID: Number - EH id returned by addMusicEventHandler.

Example: _ehID = addMusicEventHandler ["MusicStart", {hint str _this}]; playMusic "RadioAmbient3"; //hint shows ["RadioAmbient3", 0] 0 = [] spawn {sleep 2; playMusic ""}; //stops the music after 2 seconds

MusicStop

Triggers when CfgMusic sound finished playing, after being executed with playMusic command. Note that EH will not be triggered if you force stop the music with playMusic "".

This event handler needs to be added with addMusicEventHandler command and removed with removeMusicEventHandler. Passed array: [className, handlerID]

className: String - CfgMusic class name of currently played sound.
handlerID: Number - EH id returned by addMusicEventHandler.

Example: _ehID = addMusicEventHandler ["MusicStop", {hint str _this}]; playMusic "RadioAmbient3"; //hint shows ["RadioAmbient3", 0] after a few seconds

Respawn

Triggered when a unit respawns.

Passed array: [unit, corpse, ...]

unit: Object - Object the event handler is assigned to
corpse: Object - Object the event handler was assigned to, aka the corpse/unit player was previously controlling.

PostReset

From .\functions_f\Feedback\fn_feedbackInit.sqf

//checks whether PPs were reseted by engine
BIS_EnginePPReset = false;
if (isNil {player getVariable "BIS_fnc_feedback_postResetHandler"}) then {
	player setVariable ["BIS_fnc_feedback_postResetHandler", true];
	player addeventhandler ["PostReset",{BIS_EnginePPReset = true;} ];
};

Put

Triggers when a unit puts an item in a container.

Passed array: [unit, container, item]

unit: Object - Unit to which the event handler is assigned
container: Object - The container into which the item was placed (vehicle, box, etc.)
item: String - The class name of the moved item

Take

Triggers when a unit takes an item from a container.

Passed array: [unit, container, item]

unit: Object - Unit to which the event handler is assigned
container: Object - The container from which the item was taken (vehicle, box, etc.)
item: String - The class name of the taken item

SoundPlayed

Something to do with your character making noises when injured or fatigued.

WeaponAssembled

Triggers when weapon gets assembled.

Global.

Passed array: [unit, weapon]

unit: Object - Object the event handler is assigned to
weapon: Object - Object of the assembled weapon.

WeaponDisassembled

Triggers when weapon gets disassembled.

Global.

Passed array: [unit, primaryBag, secondarybag]

unit: Object - Object the event handler is assigned to
primaryBag: Object - First backpack object which was weapon dissasembled into...
secondarybag: Object - Second backpack object which was weapon dissasembled into...

Curator (Zeus) EHs

curatorObjectSelectionChanged
curatorFeedbackMessage
curatorGroupDeleted
curatorGroupDoubleClicked
curatorGroupEdited
curatorGroupPlaced
curatorGroupSelectionChanged
curatorMarkerDeleted
curatorMarkerDoubleClicked
curatorMarkerEdited
curatorMarkerPlaced
curatorMarkerSelectionChanged
curatorObjectDeleted
curatorObjectDoubleClicked
curatorObjectEdited
curatorObjectPlaced
curatorObjectRegistered
curatorPinged
curatorWaypointDeleted
curatorWaypointDoubleClicked
curatorWaypointEdited
curatorWaypointPlaced
curatorWaypointSelectionChanged

|- |  ==== HandleScore ==== |  Triggered when engine adds score to overall score of the player, usually after a kill. (currently cannot be overridden like HandleRating)<br><br>'''NOTE:''' MP only, server only. |  * unit: [[Object]] - Object the event handler is assigned to <br> * object: [[Object]] - object for which score was awarded <br> * score: [[Number]] - score added |  {{EffArg|cmd|arg|global}}{{EffArg|cmd|effs|local}} |  {{GVI|arma 3|1.29}} |-

TO DO (move to the blog)

If class Params is defined in description.ext, a simple "Parameters" GUI becomes available in Multiplayer which allows the host (or admin on dedicated server) to define custom mission parameters before mission start. These params will become available to all mission scripts via paramsArray variable, which contains Array of values selected via "Parameters" GUI.

"Parameters" GUI
Available Options
Editing Options

class Params
{
	class paramsArray_select_0
	{
		title = "Item 1"; //item name
		texts[] = {"One","Two","Three"}; //item text options (visible)
		values[] = {1,2,3}; //item value options (can only be integers)
		default = 1; //actual value (in values[]) to be set as default
	};
	class paramsArray_select_1
	{
		title = "Item 2";
		texts[] = {"Ten","Twenty","Thirty"};
		values[] = {10,20,30};
		default = 20;
	};
	class paramsArray_select_2
	{
		title = "Item 3";
		texts[] = {"One Hundred","Two Hundred","Three Hundred"};
		values[] = {100,200,300};
		default = 300;
	};
	//default value of paramsArray is [1,20,300]
};

paramsArray is available on all computers and is JIP compatible. It gets set only once on mission start. Even though admin can select different options after mission start, the value of paramsArray will remain the same as it was on mission start. Anyone can see "Parameters" GUI if it is available, but only admin or host can edit it. Players will only see default options selected when exploring "Parameters" GUI, even if host/admin changed them.

Practical example of setting mission time of the day on mission start

description.ext part:

class Params
{
	class Hours
	{
		title = "Mission Time / Hours";
		texts[] = { \
			"00","01","02","03","04","05", \
			"06","07","08","09","10","11", \
			"12","13","14","15","16","17", \
			"18","19","20","21","22","23" \
		};
		values[] = { \
			0,1,2,3,4,5,6,7,8,9, \
			10,11,12,13,14,15,16, \
			17,18,19,20,21,22,23 \
		};
		default = 12;
	};
	class Minutes
	{
		title = "Mission Time / Minutes";
		texts[] = {"00","10","20","30","40","50"};
		values[] = {0,10,20,30,40,50};
		default = 0;
	};
};

init.sqf part:

if (isServer) then { _date = date; _date set [3, paramsArray select 0]; _date set [4, paramsArray select 1]; setDate _date; };

Mission Parameters

Server admin / host can customize multiplayer missions in ROLE ASSIGNMENT menu using parameters prepared by the mission designer.

Important limitation. In an MP environment, the Paramsarray is not available on the client until some time after preinit. but before postinit so any code called upon the client should take this into consideration

Overview

Mission parameters are integer values that are passed to the mission at the beginning and which are used by the mission designer to customise user experience accordingly. The parameters are set in description.ext. They can also be either manually altered by a dedicated server admin or host during ROLE ASSIGNMENT in MP lobby from available parameters menu or by including override values in dedicated server config server.cfg. In short:

Mission maker can set up a list of parameters for the game and set default values for each
Server admin or host can change default values by selecting different options from provided parameters menu
Server owner can additionally override the default values in server config for each mission separately

In any case, a person selecting parameters from parameters menu at the beginning of the mission has the final say what those options will be.

"Parameters" GUI
Available Options
Editing Options

Param Types

There are 2 types of parameters, primary and secondary. While primary parameters are inherited from earlier versions of Arma, they are still valid and recognised by the engine.

Primary Params

Also known as param1 and param2. They are defined in the following way in description.ext, for example:

titleParam1 = "Time limit:";
textsParam1[] = {"Unlimited", "5 min", "10 min", "15 min"};
valuesParam1[] = {0, 300, 600, 900};
defValueParam1 = 900;

titleParam2 = "Score to win:";
textsParam2[] = {"Don't keep score", "50", "100", "150"};
valuesParam2[] = {0, 50, 100, 150};
defValueParam2 = 50;

Here is some info about each entry and what it means:

titleParam - This is the title that will be displayed in parameters menu available to server admin or host at ROLE ASSIGNMENT
textsParam - These are options presented to the server admin or host when they double click on the title in the parameters menu
valuesParam - These are the actual param values for each of the text options, that will be passed to the mission accordingly to chosen option
defValueParam - This is default option which would be passed to the mission if no selection was made. It must match one of the valuesParam values

The chosen option value will be stored in param1 or param2 variable (respectfully) and then broadcast to everyone as publicVariable. As mentioned before, defValueParam value can be overridden from the server config. Here is an example of such override for both params in server.cfg:

class Missions 
{
	class Mission1
	{
		template = "Mission1.Altis";
		difficulty = "Veteran";
		param1 = 600;
		param2 = 100;
	};
};

As with defValueParam provided override values must match one of the valuesParam values. The logged admin during ROLE ASSIGNMENT phase can still override even server override by selecting an option from parameters UI.

Secondary Params

You can think of the secondary params as primary params extended and wrapped in a class called Params:

class Params
{
	class name1
	{
		title = "Item 1";
		texts[] = {"One","Two","Three"};
		values[] = {1,2,3};
		default = 1;
	};
	class name2
	{
		title = "Item 2";
		texts[] = {"Ten","Twenty","Thirty"};
		values[] = {10,20,30};
		default = 20;
	};
	class name3
	{
		title = "Item 3";
		texts[] = {"One Hundred","Two Hundred","Three Hundred"};
		values[] = {100,200,300};
		default = 300;
	};
};

As you can see the structure is the same, but the names of the entries are slightly different, but consistently different (apart from default):

title - (same as titleParam) - This is the title that will be displayed in parameters menu available to server admin or host at ROLE ASSIGNMENT
texts - (same as textsParam) - These are options presented to the server admin or host when they double click on the title in the parameters menu
values - (same as valuesParam) - These are the actual param values for each of the text options, that will be passed to the mission accordingly to chosen option
default - (same as defValueParam) - This is default option which would be passed to the mission if no selection was made. It must match one of the values values

The chosen options values will be stored in paramsArray variable, in the order of appearance in the Params class and then broadcast to everyone as publicVariable. As with primary params, default value can be overridden from the server config using class names of the defined params. Here is an example of such override in server.cfg:

class Missions 
{
	class Mission1
	{
		template = "Mission1.Altis";
		difficulty = "Veteran";
		class Params
		{
			name1 = 2;
			name2 = 30;
			name3 = 100;
		};
	};
};

As override values provided must match one of the values values. The logged admin during ROLE ASSIGNMENT phase can still override the server override by selecting options from parameters UI manually.

Using Both Types

You should be careful when using both primary and secondary params in the same mission as paramsArray in this case will contain both types of parameters. For example, if just secondary params used from the example above, paramsArray would look something like this: [1,20,300]. However if both types are used at the same time, paramsArray will look something like this: [900,50,1,20,30]. The primary params are added in front of the secondary params in paramsArray.

Mission Implementation

So how does it all come together? As pointed out, params are just values that are passed over to the mission. In order to retrieve passed param value in mission use BIS_fnc_getParamValue function. For example to retrieve mission param name2:

_param = ["name2", -1] call BIS_fnc_getParamValue;

This should return 20 (in default example above) or -1 if no param with this name is found. This method is good to be used in other scripts, but there is even better way of setting mission params at the start of the mission. You can instruct the game to run a function or a script of your choice automatically by including it in the secondary Params config. Note that it is not possible to do with primary params. For example:

class Params
{
	class Daytime
	{
		title = "Time";
		texts[] = {"Morning","Day","Evening","Night"};
		values[] = {6,12,18,0};
		default = 12;
		function = "BIS_fnc_paramDaytime";
	};
};

The BIS_fnc_paramDaytime function will be executed on mission start on the server. It will also receive current value of the parameter Daytime as an argument in _this select 0. You can also instruct the game to execute a script file instead and not just on server but on every client including the JIP clients:

class Params
{
	class ViewDistance
	{
		title = "View distance (in metres)";
		values[] = {500,1000,2000,5000};
		default = 1000;
		file = "setViewDistance.sqf";
		isGlobal = 1;
	};
};

The setViewDistance.sqf script will be execVMed globally (isGlobal = 1;) on every client and param value is passed to it in _this select 0. If for some weird reason you have both function and file entries, the priority is given to function.

Killzone Kid – User

Revision as of 20:51, 6 June 2020

Often Used Links

Introduction

General MP Note

Event Scripts

Event Handler List

AnimChanged

AnimDone

AnimStateChanged

ControlsShifted

Dammaged

Engine

EpeContact

EpeContactEnd

EpeContactStart

Explosion

Fired

FiredNear

Fuel

Gear

GetIn

GetOut

HandleDamage

HandleHeal

Hit

HitPart

Init

IncomingMissile

InventoryOpened

Killed

LandedTouchDown

LandedStopped

Local

MPHit

MPKilled

MPRespawn

MusicStart

MusicStop

Respawn

PostReset

Put

Take

SoundPlayed

WeaponAssembled

WeaponDisassembled

Curator (Zeus) EHs

Overview

Param Types

Primary Params

Secondary Params

Using Both Types

Mission Implementation

Navigation menu

Search