Category:VBS: Event Handlers

From BISim Wiki
Jump to: navigation, search

Contents

Introduction

Note: For the most up to date information about Event Handlers, see Event Handlers in the VBS3 Scripting Manual in the docs folder of your VBS3 installation. For information about Event Handlers specific to a VBS version, see the equivalent topic in your version of the VBS3 Developer Reference.

Event Handlers (EHs) are attached to objects, and allow you to automatically execute custom code upon particular events being triggered by that object.

These event handlers are added to objects using the addEventHandler command, or in the object's configuration file (see below).

Multiple event handlers of the same type can be attached to an object (and are identified by the index returned by addEventHandler), and will fire in the order they were created.

General MP Note

A respawned unit still has the EHs it had before, so it is not neccessary to re-add EHs after respawning.


Other Types of Event

Event Handler List

Collisions/Damages

BeforeKilled

vbs2 1.41.gif
Fires just before a unit is killed.
Does not work with objects, and only fires after destruction, if used with vehicles.
In V2.0+ this event actually fires after the unit has been killed. (i.e. it is the same as the #Killed EH)
See also: HandleDamage

Passed array: [object]

Collision

vbs2 2.15.gif
Collision event for a named selection in the geometry.
Note: Obsolete in releases after 2.15, use #CollisionStart and #CollisionEnd instead.

Passed array: [hitObject, hitComonent, collidingObject, collisionPhase]

CollisionEnd

vbs2 1.63.gif
Fires when a collision between two objects (either PhysX or non-PhysX) ends.

Passed array, not using collision volumes: [object, []]

Passed array, using collision volumes: [object, collidingObj]


CollisionStart

vbs2 1.63.gif
Fires when a collision between two objects (either PhysX or non-PhysX) starts.

Passed array, not using collision volumes: [owner, collisions]

Passed array, using collision volumes: [object, collisionVolID, collidingObj, collidingObjVolID]

Dammaged

effects global.gif
Triggered when the object is damaged. (Must be spelled with two "m"s!)
Only fires if the damage to the hit selection is greater than 0.5.
Does not fire if damage is set via setDamage.
If simultaneous damage occurred (e.g. via grenade) EH will be triggered several times.

Passed array: [unit, selectionName, damage]

DamagedHitPart

vbs2 1.50.gif effects local.gif
Triggered when the object is damaged.
Does not fire if damage is set via setDamage.
If simultaneous damage occurred (e.g. via grenade) EH will be triggered several times.

Passed array: [target, shooter, hitzone,totaldamage,hitdamage,structdamage,hitzonecenter,hitzoneradius,selections,surfaces]

EpeContact

vbs2 1.60.gif
Fires (every frame) while a physX object is in contact with another physX object.
If used with a moving object (e.g. a car) be aware that it will constantly trigger this event while moving (due to the ground contact).

Passed array: [owner, object, ownsel, objsel, force]


EpeContactStart/EpeContactEnd

vbs2 1.60.gif
Fires when a contact between two physX objects is initiated (or ended).
If used with a moving object (e.g. a car) be aware that it will constantly trigger this event while moving (due to the ground contact).

Passed array: [owner, object, ownsel, objsel, force]


FreeFall

vbs2 2.02.gif
Fires when a unit drops from a height (e.g. falling off a building, or after being thrown into the air by an explosion). Will not fire on parachute ejections.

Passed array: [owner]


HandleDamage

vbs2 2.00.gif effects local.gif
Fires when the damage value for an object changes, and allows the adjustment of the damage value inside the EH's code section.
May fire multiple times, if multiple sections are affected, or if damage is caused by a direct, as well as indirect, hit (e.g. via grenades).
The code section of this EH can contain a return value which specifies the damage that should be applied to the target. If no return value is given, then no damage is applied (same effect as passing a 0). To use the original damage that would've been caused by the hit, _this select 2 should be returned, e.g. unit1 addEventHandler ["HandleDamage","hint 'ouch'; _this select 2"]. A return value of 1 will destroy the attached object (the example below will do this whenever the vehicle's engine is hit, any other hit will not cause any damage): car1 addEventHandler ["HandleDamage","if ('engine' in _this) then {1} else {0}"] The command setDamage should not be used in the code section of this EH, as it might lead to a dead loop (with the engine endlessly resetting and reacting to the changes of damages).
Due to the fact that this EH may fire multiple times, damage values set by one event may be overwritten by a later one, if these happen within the same frame. While full damage (as in the example above) cannot be reversed, if only partial damage is applied, then it could be overwritten by a later event (e.g. if the car example applied a damage of only 0.9, then a damage event to the "hull" could negate the originally applied damage).

Passed array: [target, selection, damage, shooter, bullet]


HandleHeal

vbs2 2.00.gif
Fires when a unit is healed by another one.
Does not fire when healing at an ambulance vehicle or tent.
If the EH code returns nothing (or false), then the normal healing process is activated. If it returns true, then this EH will continue to fire until either the target's health is set to full (via setDamage), or the AISFinishHeal command is executed. player addEventHandler["HandleHeal","if (okToHeal) then {false} else {AISFinishHeal [_this select 0,_this select 1,false]}"]

Passed array: [target, healer, isMedic]


Hit

effects local.gif
Triggered when the unit is hit and damaged.

Will only fire if a minimum threshold of damage has been reached (about .06). Otherwise, even if the object damage did increase, this EH will not be triggered. If damage has been disabled, the event will never fire, even if the object was hit.
In addition, if an object is killed/destroyed right away with the first hit, this EH may not trigger either; only the killed EH will fire in that case.
See MPHit for a global "Hit" EH for MP scenarios.

Passed array: [target, shooter, damage]


HitPart

vbs2 1.18.gif effects local.gif
Runs when the object it was added to gets hit/injured/damaged.
Unlike the "Hit" event, this one will fire even if there is no damage (e.g. because it was disabled).
It returns the position and component that was hit on the object within a nested array (one for each selection that was hit).
See also: getHitPoints

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


Killed

effects local.gif
Triggered when the unit is killed.
See MPKilled for a global "Killed" EH for MP scenarios.

Passed array: [unit, killer]

turretDriveConnected / turretDriveDisconnected

vbs3 17.2.0.gif
Triggered when contact between a PhysX object and a configured vehicle turret is initiated (connected) / ended (disconnected).

Passed array: [owner, turret, force, angular speed]

WheelCollisionEnd

vbs3 17.1.0.gif
This event occurs when wheel collision with the target object ends (see WheelCollisionStart).

Passed array: [vehicle, selection, trgObject, hitPoint]

WheelCollisionStart

vbs3 17.1.0.gif
This event occurs when wheel collision with the target object starts (also see WheelCollisionEnd).

  1. Drive the vehicle over the speed bump (which has the WheelCollisionStart event handler attached to it) and stop there (with at least one of the wheels touching the speed bump).
  2. WheelCollisionStart executes.
  3. Branch Point Save.
  4. Drive off the speed bump.
  5. WheelCollisionEnd executes.
  6. Branch Point Load.
  7. WheelCollisionEnd executes.
  8. WheelCollisionStart executes.
  9. Drive off the speed bump.
  10. WheelCollisionEnd executes.

Passed array: [vehicle, selection, trgObject, hitPoint]

Editor

Delete

vbs2 1.14.gif effects local.gif
Runs just before an object is deleted. Object can be deleted in several ways, few of which are: the deleteVehicle command, the RTE, or LVC Game.

Passed array: [object]

Note: Delete EH can only be added within scripts using addEventHandler scripting command. If used in a config, an error will occur during packing of content.
Note: To ensure the parameters are passed correctly before the object is deleted, it is strongly recommended that you use call rather than execVM or spawn

Example:
_object addEventhandler ["delete","_this call compile preProcessFile 'fn_my_function.sqf'"];


Deleted

vbs2 1.30.gif effects global.gif
Identical to the Delete EH, except this EH can be added in config.

Passed array: [object]

Note: To ensure the parameters are passed correctly before the object is deleted, it is strongly recommended that you use call rather than execVM or spawn

Example:
deleted="_this call compile preProcessFile 'fn_my_function.sqf'"


GroupChangedRTE

vbs2 1.35.gif effects global.gif
Added to a Side, not an object. Triggered only if RTE is open, when a change occurs to a specific group's or subgroup status. Also triggered on creation of new group, or deletion of an existing group.

Passed array: [group]


Paste

vbs2 1.50.gif
Triggered when an object has been copied and pasted in the editor.
If a vehicle is copied, the EH will fire once for the vehicle, and once for every crew member.

Passed array: [original, copy]


PlayerChangedRTE

vbs2 2.11.gif
Added to a Side, not an object. V3.20+: Can also be used on units.
A unit's ownership by a player has changed while the editor is open.
Also see PlayerChanged

Passed array: [unit, mode]


Units

AnimChanged

effects global.gif
Triggered when a new animation is started.

Passed array: [unit, anim, currentPhase, targetPhase]


AnimDone

Triggered when an animation has reach its end position.

Passed array: [unit, anim]


AnimStateChanged

vbs2 2.00.gif
Triggered when an animation state changes.
Unlike AnimChanged and AnimDone, it is triggered for all animation states in a sequence.

Passed array: [unit, anim]


CoverReached

vbs2 2.12.gif
Triggered when a unit in combat mode reached a cover position.

Passed array: [unit, coverType, coverPosition, coverEntryPosition]


Danger

vbs2 2.12.gif
Triggered when an AI unit encounters a danger indicator.

Passed array: [unit, dangerType, dangerPosition, until, cause, script]


GestureChanged

vbs3 3.10.gif
Triggered when a new gesture is started or completed.

Passed array: [unit, gesture]


GestureDone

vbs3 3.10.gif
Triggered when a gesture is completed.

Passed array: [unit, gesture]


GroupChanged

vbs2 1.35.gif effects global.gif

Added to a Side, not an object. Triggered when a change occurs to a specific group's or subgroup status. Also triggered on creation of new group, or deletion of an existing group.
See also #GroupChangedRTE.

Passed array: [group]


LoadOutChanged (Unit)

vbs2 1.18.gif vbs2 1.30.gif effects local.gif

Runs whenever a weapon or magazine is added/removed from a unit or vehicle. This could occur as a result of scripting commands (such as addWeapon or removeMagazine), or it could happen as a result of in-game actions such as reloading magazines, dropping weapons, etc.

Passed array: [object]

Note: In versions below 1.30, these event handlers will be removed from nearby objects when a player uses the inventory (and thus can not be considered 100% reliable). This does not happen in v1.30+ (and thus can be considered 100% reliable).


Moved (Unit)

vbs3 3.7.gif
A unit/vehicle/object has moved (either by itself, or it was dragged in the editor).
If a unit is inside a vehicle, and that vehicle moves, then only the event for the vehicle will fire.

Passed array: [unit, oldPos, oldDir, oldUp, oldDirS, newPos, newDir, newUp, newDirS]

NameChanged

vbs3 3.4.gif
Added to a Side, not an object. A unit's name was assigned via setUnitName.
Event will fire even if the new name is the same as the old one.

Passed array: [unit, newName, oldName]


PathPlanFailed (Unit)

vbs2 1.60.gif
Unit/vehicle was not able to reach a assigned destination (assignment can be via waypoint, move commands, or group order).

Passed array: [unit, destination, retry]


PlayerChanged

vbs2 2.11.gif
Added to a Side, not an object. V3.20+: Can also be used on units.
A unit's ownership by a player has changed.
Also see PlayerChangedRTE

Passed array: [unit, mode]


PositionChangedMan

vbs2 2.05.gif
Runs when a person either enters, exits, or changes positions inside a vehicle.
Also see PositionChanged, for a vehicle-based EH.

Passed array: [person, vehicle, positionFromArray, positionToArray]


ResetFatigue

vbs2 2.15.gif
Runs when a unit's fatigue level is reset via resetFatigue.

Passed array: [unit, fatigue]


Respawn

vbs2 1.18.gif effects local.gif
Runs when the object respawns. This EH is only fired where the respawned unit is local, if its not known where the unit is local (or will be local when it is respawned), you have to add it on all machines.
See MPRespawn for a global "Respawn" EH for MP scenarios.

Passed array: [new unit, old unit]

Note: This EH is persistent, thus unit once respawned will have it again.


Revived

vbs3 3.8.1.gif
Triggered after a unit is revived.

Passed array: [man]

Suppressed

vbs2 1.18.gif effects global.gif
Runs each time a unit is suppressed (by incoming rounds).

Passed array: [unit, who fired, type, distance, position, projectile]

Note: "Suppression of user" must be enabled in difficulty settings for this event to trigger. This event will trigger for both AI as well as player units.

UPRPlaybackEnd

vbs3 3.7.gif
Fires when the playback of a UPR recoding ends.

Passed array: [unit, stopped]


UPRRecordEnd

vbs3 3.7.gif
Fires when a UPR recording ends.

Passed array: [unit, stopped]


WaypointComplete

vbs2 1.00.gif effects global.gif
This event must be added to a Group, not an individual unit or vehicle. It is triggered when that group completes a waypoint.

Passed array: [group, index]

Vehicles

AnimChanged

vbs2 1.60.gif
Fires constantly during an animation. See Units#AnimChanged for details.


AnimDone

vbs2 1.60.gif
See Units#AnimDone for details.


AfterGetIn/AfterGetOut

vbs2 1.50.gif
Triggered after a unit gets in or out of a vehicle.

Passed array: [vehicle, position, unit]


BeforeGetIn/BeforeGetOut

vbs2 1.50.gif
Triggered just before a unit gets in or out of a vehicle.
In V2.0+ this event actually fires after the unit has entered/left the vehicle. (i.e. it is the same as the #AfterGetIn/AfterGetOut EH)

Passed array: [vehicle, position, unit]


CargoChanged

vbs2 1.18.gif effects global.gif
Runs whenever a weapon or magazine is added / removed from the cargo space of a vehicle. This could occur as a result of running scripting commands (such as addWeaponCargo or clearMagazineCargo), or it could happen as a result of in-game actions, such as an AI soldier taking out gear from a vehicle.
The event handler has the following considerations:

  1. The magazines of an infantry unit are in their equipped space (does not trigger the event handler); when the magazines are moved in a vehicle, they are in the vehicle cargo space (triggers the event handler).
  2. When a weapon is moved from the primary slot of an infantry unit to their backpack, it is considered as moving the weapon from the equipped space into the cargo space of the infantry unit (triggers the event handler).
  3. For infantry units, magazine space is not considered cargo space, even if the infantry unit has a backpack (moving a magazine to an infantry unit does not trigger the event handler).

Passed array: [object]

Note: before v1.30, these event handlers are removed from nearby objects when a player uses the inventory; therefore, these event handlers cannot be considered reliable in versions before 1.30.

Engine

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

Passed array: [vehicle, engineState]


Fuel

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

Passed array: [vehicle, fuelState]


Gear

effects global.gif
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").

Passed array: [vehicle, gearState]


GetIn/GetOut

effects global.gif
Triggered when a unit enters or leaves the object (only useful when the event handler is assigned to a vehicle). It does not trigger upon a change of positions within the same vehicle. It also is not triggered by the moveInX commands.

Passed array: [vehicle, position, unit]


GetInMan/GetOutMan

vbs2 1.18.gif effects global.gif
Triggered when a unit enters or leaves a vehicle. It does not trigger upon a change of positions within the same vehicle. This event is attached to a person, not a vehicle like the GetIn event.

Passed array: [unit, position, vehicle]


LandedStopped

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

Passed array: [plane, airportID]


LandedTouchDown

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

Passed array: [plane, airportID]


LaserFired

vbs3 17.1.0.gif
Triggered when a vehicle laser range finder is invoked. The returned values are relative to the vehicle.

If the event-handler addEventHandler command returns true (for example, tank addEventHandler["LaserFired","hint 'fired'; true"]), lasing is interrupted (and the distance displayed appears in red).

If a range finder is returning an illegal range (for example, too far or too close, as indicated by an "ERR" message), the event handler returns the last lased distance, in addition to the new directions.

Depending on the vehicle or weapon configuration, multiple returns are provided.

Passed array: [distance, elevation, turn, vehicle, turret, position, direction, distances]


LoadOutChanged (Vehicle)

See #LoadOutChanged (Unit)


Moved (Vehicle)

See [#Moved (Unit)]


PathPlanFailed (Vehicle)

See [#PathPlanFailed (Unit)]]


PositionChanged

vbs2 1.24.gif effects global.gif
Added to a vehicle. Runs when a person either enters, exits, or changes positions inside a vehicle.
Also see PositionChangedMan, for a unit-based EH.

Passed array: [vehicle, person, positionFromArray, positionToArray]

Note: The event will be called whenever you change one manned vehicle type in the OME for another. This includes the removal of the original crew, in which case null objects will be passed to the event along with the vehicle positions.

TurnIn/TurnOut

vbs2 1.19.gif effects global.gif
Triggered when a unit turns in (or out of) a vehicle's turret position.

Passed array: [vehicle, unit, turretpath]

Weapons/Shots

AmmoCreate

vbs3 3.8.gif
Fires whenever any object of cfgAmmo is created.

Passed array: [bullet, shooter, target, position, velocity, selection, ammo, direction, exploded] (the same array elements as AmmoExplode/AmmoHit, even though some of them have no meaning for create ammo — e.g. target and exploded).

AmmoDelete

vbs3 3.4.gif
Fires when the shot is deleted via deleteVehicle.

Passed array: [bullet, shooter, target, position, velocity, selection, ammo, direction, exploded] (the same array elements as AmmoExplode/AmmoHit, even though some of them have no meaning for deleted ammo — e.g. hit information).


AmmoExplode/AmmoHit

vbs2 1.18.gif vbs2 1.30.gif effects local.gif
EH is assigned to a bullet (found via the "Fired" EH, for example).
"AmmoHit" runs when the ammunition hits something (even if it ricochets), while "AmmoExplode" only runs when the ammo explodes or terminally impacts something.
Scripted "AmmoHit" events will only fire if the bullet has already traveled for a certain distance (about 40m or 0.03 seconds).

Passed array: [bullet, shooter, target, position, velocity, selection, ammo, direction, exploded]

Note: In versions below 1.3, these EHs only works from CfgAmmo (you cannot add it with addEventHandler). However, in v1.3 and above the "AmmoHit" EH can be added via the script command.


ChangedWeapon

vbs2 1.31.gif effects global.gif
Added to the config of a weapon (not added via the addEventHandler scripting command)! Runs whenever this weapon is added or removed from a unit.

Passed array: [owner, weapon, added?]


Explosions

vbs2 1.45.gif
Fires when an explosion happens in the mission (only works with player units).

Passed array: [positionX, positionY, positionZ, indirectHit, indirectHitRange, energyFactor]


Fired

vbs2 1.19.gif effects global.gif
Executes when a weapon is fired.
For addons, this Event Handler can be configured to run from either CfgWeapons or CfgVehicles.

Passed array: [unit, weapon, muzzle, mode, ammo, magazine, projectile]


FiredNear

vbs2 2.00.gif
Executes when a weapon is fired nearby.
Does not respond to explosions (e.g. IEDs or artillery) or thrown projectiles.
The effective range depends on the environment. In an open area this EH may fire up to a distance of up 80m, whereas in an urban area it may be less than 40m.
The caliber and ammo type do not affect the trigger range (i.e. a silenced 9mm pistol may have the same range as a 50cal machine gun).
This handler will continue to fire, even after the unit it's attached to is dead.
For addons, this Event Handler can be configured to run from either CfgWeapons or CfgVehicles.

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


IncomingFire

vbs2 2.02.gif
Triggered when a bullet was fired at the associated object.

Passed array: [unit, shooter, ammo, distance, position, projectile]

IncomingMissile

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

Passed array: [unit, ammo, shooter, projectile]

LaserFired

vbs2 1.51.gif
Executes when a vehicle's laser range finder is invoked.
Returned values are relative to the vehicle.
If the EH command returns true (e.g. tank addEventHandler["LaserFired","hint 'fired'; true"]), lasing will be interrupted (and the distance displayed will show up red).
If a range finder is returning an illegal range (too far or too close, as indicated by an "ERR" message), this EH will return the last lased distance, in addition to the new directions.

Passed array: [distance, elevation, turn]


SelectWeapon

vbs2 2.02.gif
Runs after the user changes weapon or weapon mode (such as Single to FullAuto, or from rifle to grenades).
Passed array: [object, previous weapon, previous weapon, previous muzzle, current muzzle, previous mode, current mode]

Other

AttachTo

vbs2 1.19.gif effects global.gif
Runs whenever an object is attached to another using the attachTo scripting command. Also runs when an object is detached from another object.

Passed array: [child, parent, position]


Init

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

Passed array: [unit]


VariableChanged

vbs2 2.09.gif
Runs whenever a setVariable command is run for the specified unit/object.
It doesn't matter if the variable actually changed, or if it was created or destroyed — whenever any object variable for the specified owner is set, the event will fire. (V3.4+: Event will also fire if variable is changed within AAR.)

Passed array: [owner, variable, newval, oldval]


VariableNameChanged

vbs3 3.4.gif
Added to a Side, not an object. An object's variable name was assigned via setVehicleVarName.
Event will fire even if the new name is the same as the old one.

Passed array: [unit, newName, oldName]


Multiplayer

The following events have to be declared with the addMPEventHandler command, and the defined action will be executed on all MP clients.

MPHit

vbs2 2.00.gif effects global.gif
Triggered when the unit is hit/damaged.
Same behavior as regular "Hit" EH, but effect is global.

Passed array: [target, shooter, damage]


MPKilled

vbs2 2.00.gif effects global.gif
Triggered when the unit is killed.
Same behavior as regular "Killed" EH, but effect is global.

Passed array: [unit, killer]


MPRespawn

vbs2 2.00.gif effects global.gif
Triggered when the object respawns.
Same behavior as regular "Respawn" EH, but effect is global.

Passed array: [new unit, old unit]

Subcategories

This category has only the following subcategory.

E

Pages in category "VBS: Event Handlers"

The following 7 pages are in this category, out of 7 total.

C

G

H

S

V

V cont.

Media in category "VBS: Event Handlers"

The following 2 files are in this category, out of 2 total.

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox