Events - Add `CBA_fnc_addBISPlayerEventHandler` for adding EHs to just the player (from ACE3)

[LinkIsGrim]

When merged this pull request will:

• Title, see https://github.com/acemod/ACE3/pull/10056, though this is not intended for public usage/API (it's a secret tool that will help us later).

~I'm not sure if the code block below is equivalent, since there's no ACE_player here.~ It isn't.

if (_ignoreVirtual && {(unitIsUAV focusOn) || {getNumber (configOf focusOn >> "isPlayableLogic") == 1}}) exitWith {};

[PabstMirror]

I think we can replace ace_player with call CBA_fnc_currentUnit iirc focusOn might be funny when controlling a uav, not sure

[commy2]

Just a few thoughts.

• It stylistically correctly omits a version to remove the event handlers.

• It is not thread-safe (spawn-pseudo threads), like most the rest of CBA tbf.

• This seems related to common component addPlayerAction, more so than events component addPlayerEventHandler. The names are unfortunate.

I don't personally like CBA_fnc_addPlayerAction and always thought of it as legacy code. I would always recommend to simply add user actions (and by extension event handlers) to every unit and then to quit early via guard clause. Is the mental overhead required for using such an obscure framework justified considering one could simply write:

if (_unit != player) exitWith {};

?

[LinkIsGrim]

This is only ever intended for internal use, to replace the polling in player events (hence, no removal option) and so the mental overhead is a one-time thing during implementation IMO. I don't like the idea of adding the EHs to every unit, due to the overhead (though it might still be better than polling). unit playerEH doesn't fire that often (basically only on respawn) for a non-curator on the other hand, and that's already laggy, so it doesn't matter.

I can make this exit on canSuspend, but again, this should only ever be called by CBA itself a few times at the start of a mission.

[PabstMirror]

There is some performance savings by only adding events you need. e.g. FiredNear could almost be considered n^2 based on unit count

We can make it safe by wrapping in a CBA_fnc_directCall; like https://github.com/CBATeam/CBA_A3/blob/master/addons/events/fnc_addEventHandler.sqf

[LinkIsGrim]

Implemented as public function. Added removal, thread-safety, and multiple events of the same type can be added now.

Do I need to touch anything myself for docs?