Adding Event Handlers to Classes of Objects - CBATeam/CBA_A3 GitHub Wiki
Class Event Handlers can be used to add the usual object event handlers to whole classes of objects including their child classes. This can be used to add the same event to multiple objects at once and to ensure that these events apply to objects that are created during a mission (i.e. via createUnit
or createVehicle
).
The concept is very similar to the Extended Event Handlers (XEH), but there are two key differences: Class Event Handlers can be used in mission scripts like the init.sqf
and support units and vehicles which do not follow the necessary steps to be compatible with XEH.
https://github.com/CBATeam/CBA_A3/wiki/Extended-Event-Handlers-%28new%29#supported
Description:
Add an eventhandler to a class and all children.
Parameters:
0: _className - The classname of objects you wish to add the eventhandler too. Can be a base class. <STRING>
1: _eventName - The type of the eventhandler. E.g. "init", "fired", "killed" etc. <STRING>
2: _eventFunc - Function to execute when event happens. <CODE>
3: _allowInheritance - Allow event for objects that only inherit from the given classname? [optional] <BOOLEAN> (default: true)
4: _excludedClasses - Exclude these classes from this event including their children [optional] <ARRAY> (default: [])
5: _applyInitRetroactively - Apply "init" event type on existing units that have already been initilized. [optional] <BOOLEAN> ((default: false)
Returns:
_success - Whether adding the event was successful or not. <BOOLEAN>
Examples:
(begin example)
["CAManBase", "fired", {systemChat str _this}] call CBA_fnc_addClassEventHandler;
["All", "init", {systemChat str _this}] call CBA_fnc_addClassEventHandler;
["Car", "init", {(_this select 0) engineOn true}, true, [], true] call CBA_fnc_addClassEventHandler; //Starts all current cars and those created later
(end)
The function only adds the event handler on the machine where the function is executed. If the event function should be executed on a remote machine, CBA_fnc_addClassEventHandler
has to be executed on that client as well.
The same limitations regarding object locality that apply to object event handlers like respawn
, killed
etc. apply to Class Event Handlers as well. A "respawn"-Class Event Handler will only fire on the machine where the respawned unit is local.
["CAManBase", "Fired", {systemChat str _this}] call CBA_fnc_addClassEventHandler;
This will show a chat message every time a soldier fires a weapon. It is advised to use CAManBase
instead of Man
when dealing with soldiers, because Man
is the parent class of all animals, including the randomly spawning rabbits, snakes and fish. Using CAManBase
slightly reduces the overhead that would happen when any of these spawn (which actually happens pretty frequently).
["AllVehicles", "GetIn", {hint str _this}] call CBA_fnc_addClassEventHandler;
This event happens every time a soldier enters a vehicle.
["All", "InitPost", {diag_log _this}, nil, nil, true] call CBA_fnc_addClassEventHandler;
Init
and InitPost
events can execute code retroactively for already existing objects. This is useful when working with scheduled scripts like init.sqf
or a postInit
function defined in CfgFunctions
.
Class Event Handlers will only work on mission objects. These are objects placed by the mission maker or objects created during the mission via createUnit
and createVehicle
. Class Event Handlers do not work on map objects (houses, trees, stones etc. not placed by the mission maker).
Class Event Handlers can not be removed. If an event should be "disabled" during a mission, it is advised to use a global boolean variable combined with exitWith
instead.
My_disableFiredEvent = true;
["CAManBase", "killed", {
if (My_disableFiredEvent) exitWith {};
...
}] call CBA_fnc_addClassEventHandler;