Arma 3: Event Handlers/HandleDamage

From Bohemia Interactive Community
Jump to navigation Jump to search
Work-in-Progress : Attempt to clarify the oddness that is "HandleDamage".

Just started, and a long way to go. Much placeholding. So nonsense.

This is currently an orphaned page, and should remain so until complete (as much as any page ever is).

The HandleDamage Event Handler (EH) is somewhat unpredictable, and produces what could be considered unexpected returns, so deserves a little more explanation than other EHs.

Usage

To apply this EH to e.g. a vehicle like e.g. a Pawnee, we might add something like the following to its initialization field:

this addEventHandler ["HandleDamage", { _v = _this select 0; if (alive _v) then { _s = _this select 1; if (_s == "") then { _s = "Pawnee"; } else { if (_s == "?") then { _s = "unnamed section"; }; }; hintSilent format ["The %1 is %2 damaged.", _s, _this select 2]; } else { _v removeAllEventHandlers "HandleDamage"; hintSilent "The Pawnee was destroyed"; }; }];

However, if we shot the Pawnee, crashed it, or it was hit by a rocket or grenade blast, the hints we'd see might appear to make little sense.

To better understand what to expect when this EH is triggered, it's perhaps easiest to dump all the details to the rpt file.

this addEventHandler ["HandleDamage", { _v = _this select 0; if (alive _v) then { diag_log _this; } else { _v removeAllEventHandlers "HandleDamage"; hintSilent "The Pawnee was destroyed"; }; }];

Now if we damage the Pawnee, we might read from the rpt file, something like:

[31832080# 163961: heli_light_01_f.p3d,"",1.83398e-006,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"fuel",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"hull",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"engine",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"avionics",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"tail rotor",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"main rotor",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"glass1",0.0160021,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"",0.000976418,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"fuel",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"hull",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"engine",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"avionics",0.666174,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"tail rotor",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"main rotor",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"glass1",0.0441059,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"",0.00214815,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"",0.00308405,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"fuel",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"hull",0.092359,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"",0.00321081,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"fuel",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"hull",0.092359,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"engine",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"avionics",0.666174,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"tail rotor",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"main rotor",0.184457,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"",0.0032109,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"fuel",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"hull",0.092359,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"engine",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"avionics",0.692207,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"tail rotor",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"main rotor",0.184457,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"glass1",0.0673573,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"",0.00321226,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"fuel",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"hull",0.092359,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"engine",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"avionics",0.746253,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"tail rotor",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"main rotor",0.184457,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"glass1",0.0673573,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]
[31832080# 163961: heli_light_01_f.p3d,"glass2",0.0148264,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]

All of those 44 logs were triggered by only 5 shots at close range from a MX 6.5mm.

Now we can evaluate the logs:

Returns

Each trigger of this EH returns 5 pieces of information available to us as selections 0-4 of _this.

If this EH is applied to vehicle with a driver, this will be the driver.
  • _this select 1 gives us the name of the section of the Object this trigger is referring to.
An empty string denotes the whole Object this EH is applied to.
  • _this select 2 gives us the current damage level (between 0 (no damage) and 1 (destroyed)) of the section of the Object this trigger is referring to.
If referring to the whole Object, this Number will be the same as damage previously was (see below for details).
  • _this select 3 gives us the source of the cause of the damage this trigger is referring to.
The unit responsible if the cause of the damage is a bullet, rocket, grenade, explosive etc.
<NULL-object> if the damage was caused by e.g. a collision with an environmental element such as e.g. a tree, wall or the ground.
  • _this select 4 gives us the cause of the damage this trigger is referring to.
The bullet, explosive, rocket, grenade etc. name or an empty string if damage is caused by a collision with e.g. a tree, wall or the ground.

Cyclic updates

The returns per event (an incident like an explosion or bullet hit) can often be in the form of multiple triggers, and often multiple triggers for the same sections - even sections that haven't been damaged.

A simple way to understand the returns is to consider the path of a bullet through an unarmoured vehicle. For example's sake, we'll imagine a 6.5mm round fired from close range at a civilian car windscreen:

  1. The bullet hits the windscreen.
  2. The windscreen is damaged.
  3. The bullet passes through the windscreen and is deflected toward the instruments (dashboard).
  4. The bullet hits the instruments.
  5. The instruments are damaged.
  6. The bullet passes through the instruments and is deflected toward the side window.
  7. The bullet hits the side window.
  8. The side window is damaged.
  9. The bullet passes through the side window and is no longer any threat to the vehicle.

In this imagined event, 3 sections of the vehicle are damaged, and the vehicle as a whole is consequently considered damaged.

The first trigger of this EH will return something like:

[car,"",0,B Alpha 1-1:1 (Player Name),"B_65x39_Caseless"]

We might expect the section name to be that of the windscreen since the windscreen was hit first, but instead the first trigger tells us about the damage done to the vehicle as a whole. However, the first trigger of this EH if applied to a previously undamaged Object will reveal that the Object as a whole is undamaged; this is because the damage to each section of the Object has not yet been taken into account.

We'll then likely get another trigger that could look something like:


And another:


And another:


And so on, until eventually we have been told about every damaged section up to and including the windscreen.

This is where the cyclic nature of the returns begins to reveal itself.

The bullet continues on its path toward the instruments, and when it hits them we get another round of triggers in the same section order as before - starting with the vehicle as a whole which now reports that it is damaged because of the inclusion of the damage done to the windscreen.


And another:


And another:


And so on, until eventually we have been told about every damaged section up to and including the instruments.

This cyclical reporting continues until the bullet has stopped, slowed enough that it is no threat or has left the area.

Handling the Handle

All of the reports from this EH during this event are issued within the same frame, whereas tickTime may increment during the event.