ACE3/events-framework.md at aed2222b8159dbfbea00526169fd8fa85870ee6b

mirror of https://github.com/acemod/ACE3.git synced 2024-08-30 18:23:18 +00:00

* Update PBO checking

* Added kicking of clients without ACE loaded

* Update fnc_errorMessage.sqf

* Update fnc_checkVersionNumber.sqf

* More compatibility for #9568

* Cleanup

* Minor cleanup + added server source

* update outdated/not present error message

* check version number fixes

* Update fnc_errorMessage.sqf

* Changed error names

Server is always right, client has either older or newer versions, or missing or additional addons

* Improved ACE detection method

* Tweaks and fixes

* Try another approach

* Update events-framework.md

* Update XEH_postInit.sqf

* Update fnc_checkVersionNumber.sqf

* Removed check for non-ACE clients

* Update XEH_postInit.sqf

* Cleanup

* Remove rogue change

* Improved message display in systemChat

* Update fnc_checkPBOs.sqf

* Removed loop variable initialisers

* Fixed header

* Updated headers

---------

Co-authored-by: Grim <69561145+LinkIsGrim@users.noreply.github.com>
Co-authored-by: LinkIsGrim <salluci.lovi@gmail.com>

2024-06-22 15:52:59 +02:00

16 KiB

Raw Blame History

layout	title	description	group	order	parent	mod
wiki	Events Framework	Explains how to use CBA event handlers with ACE3 events used to trigger or allow triggering of specific functionality and lists all documented events.	framework	5	wiki	ace

1. Event Handlers

Event handlers in ACE3 are implemented through CBA's Event System. They should be used to trigger or allow triggering of specific functionality.

2. Events List

ACE3 uses many events internally, this is not a complete list; but it should list most publicly usable events.

2.1 Fired Event Handlers (`ace_common`)

Different events for what type of unit has fired. E.G.: If you only need to do action when player's weapon fires, this will be faster than adding an XEH for everything. The vehicle events will also have the following local variables available _gunner (OBJECT), _turret (ARRAY).

Event Key	Parameters	Locality	Type	Description
`ace_firedPlayer`	[_unit, _weapon, _muzzle, _mode, _ammo, _magazine, _projectile]	Local	Listen	ACE_player fires
`ace_firedPlayerNonLocal`	[_unit, _weapon, _muzzle, _mode, _ammo, _magazine, _projectile]	Local	Listen	Any other player fires
`ace_firedNonPlayer`	[_unit, _weapon, _muzzle, _mode, _ammo, _magazine, _projectile]	Local	Listen	AI fires
`ace_firedPlayerVehicle`	[_vehicle, _weapon, _muzzle, _mode, _ammo, _magazine, _projectile]	Local	Listen	ACE_player turret fires
`ace_firedPlayerVehicleNonLocal`	[_vehicle, _weapon, _muzzle, _mode, _ammo, _magazine, _projectile]	Local	Listen	Any other player turret fires
`ace_firedNonPlayerVehicle`	[_vehicle, _weapon, _muzzle, _mode, _ammo, _magazine, _projectile]	Local	Listen	AI turret fires
`ace_versioning_clientCheckDone`	_missingAddonsClient, _additionalAddonsClient, _olderVersionsClient, _newerVersionsClient	Local	Listen	When PBO checking has finished on a client
`ace_versioning_serverCheckDone`	_serverFiles, _serverVersions	Local	Listen	When PBO checking has finished on the server

2.2 Medical (`ace_medical`)

Event Key	Parameters	Locality	Type	Description
`ace_unconscious`	[_unit, _state(BOOL)]	Global	Listen	Unit's unconscious state changed
`ace_placedInBodyBag`	[_target, _bodyBag, _isGrave]	Global	Listen	Target placed into a bodybag Note: (Target will soon be deleted, target could be a bodybag)
`ace_placedInGrave`	[_target, _grave]	Global	Listen	Target placed into a grave, _grave will be objNull if `Create Grave Markers` is disabled Note: (Target will soon be deleted)
`ace_treatmentStarted`	[_caller, _target, _selectionName, _className, _itemUser, _usedItem, _createLitter]	Local	Listen	Treatment action has started (local on the _caller)
`ace_treatmentSucceded`	[_caller, _target, _selectionName, _className, _itemUser, _usedItem, _createLitter]	Local	Listen	Treatment action is completed (local on the _caller)
`ace_treatmentFailed`	[_caller, _target, _selectionName, _className, _itemUser, _usedItem, _createLitter]	Local	Listen	Treatment action has been interrupted (local on the _caller)
`ace_medical_handleUnitVitals`	[_unit, _deltaT]	Local	Listen	Vitals update ran for unit, _deltaT is the time elapsed since the previous vitals update (local to _unit)
`ace_medical_treatment_bandaged`	[_medic, _patient, _bodyPart, _className, _itemUser, _usedItem, _createLitter, _bandageEffectiveness]	Local	Listen	_medic has bandaged _patient, the array can be modified to change treatment parameters (local to _medic)

2.3 Interaction Menu (`ace_interact_menu`)

MenuType: 0 = Interaction, 1 = Self Interaction

Event Key	Parameters	Locality	Type	Description
`ace_interactMenuOpened`	[_menuType]	Local	Listen	Interaction Menu Opened
`ace_interactMenuClosed`	[_menuType]	Local	Listen	Interaction Menu Closed
`ace_interact_menu_newControllableObject`	[_typeOf]	Local	Listen	New controlable object, only fires once per type (add self interactions)

2.4 Cargo (`ace_cargo`)

Event Key	Parameters	Locality	Type	Description
`ace_addCargo`	[_item (CLASSNAME or OBJECT), _vehicle, _cargoCount]	Target	Callable	Scripted way to add cargo to vehicle
`ace_cargoLoaded`	[_item, _vehicle]	Global	Listen	Cargo has been Loaded into vehicle
`ace_cargoUnloaded`	[_item, _vehicle, _unloadType]	Global	Listen	Cargo has been Unloaded from vehicle

2.5 Captives (`ace_captives`)

Event Key	Parameters	Locality	Type	Description
`ace_captiveStatusChanged`	[_unit, _state(BOOL), _reason ("SetHandcuffed" or "SetSurrendered"), _caller]	Global	Listen	Unit's captivity state changed
`ace_captives_setSurrendered`	[_unit, _state(BOOL)]	Target	Callable	Sets a unit to either start or stop surrendering
`ace_captives_setHandcuffed`	[_unit, _state(BOOL)]	Target	Callable	Sets a unit to either start or stop being handcuffed
`ace_captives_escortingCaptive`	[_unit, _state(BOOL), _caller]	Local	Listen	Caller starting or stopping escort of unit

2.6 Settings (`ace_common`)

Event Key	Parameters	Locality	Type	Description
`ace_settingsInitialized`	[]	Local	Listen	All modules are read and settings are ready
`ace_settingChanged`	[_name,_value]	Local	Listen	A setting has been changed

2.7 Tagging (`ace_tagging`)

Event Key	Parameters	Locality	Type	Description
`ace_tagCreated`	[_tagObject, _texture, _tagAttachedTo (can be null), _unitThatCreated]	Global	Listen	Tag is created

2.8 Explosives (`ace_explosives`)

Event Key	Parameters	Locality	Type	Description
`ace_allowDefuse`	[_mine, _allow]	Global or Target	Callable	Set allowance of the dynamic defusal action on a mine
`ace_tripflareTriggered`	[_flareObject, [_posX, _posY, _posZ]]	Global	Listen	Tripflare triggered
`ace_explosives_clackerAdded`	[_unit, _explosive, _id]	Local	Listen	Clacker added to explosive
`ace_explosives_place`	[_explosive, _dir, _pitch, _unit]	Global	Listen	Explosive is armed
`ace_explosives_setup`	[_explosiveVehicle, _magClassname, _unit]	Global	Listen	Explosive is placed in the world

2.9 Logistics Wirecutter (`ace_logistics`)

Event Key	Parameters	Locality	Type	Description
`ace_wireCuttingStarted`	[_unit, _fence]	Global	Listen	Fence cutting started

2.9 Refuel (`ace_refuel`)

Event Key	Parameters	Locality	Type	Description
`ace_refuel_started`	[_source, _target]	Local	Listen	Refuelling has started
`ace_refuel_tick`	[_source, _target, _amount]	Local	Listen	Amount of fuel transferred in a tick
`ace_refuel_stopped`	[_source, _target]	Local	Listen	Refuelling has stopped

2.10 Cook Off (`ace_cookoff`)

Event Key	Parameters	Locality	Type	Description
`ace_cookoff_cookOff`	[_vehicle, _intensity, _instigator, _smokeDelayEnabled, _ammoDetonationChance, _detonateAfterCookoff, _fireSource, _canRing, _maxIntensity, _canJet]	Global	Listen	Vehicle cook-off has started
`ace_cookoff_cookOffBox`	[_box, _source, _instigator, _delay]	Global	Listen	Ammo box cook-off has started
`ace_cookoff_engineFire`	[_vehicle]	Global	Listen	Engine fire has started

2.11 Attach (`ace_attach`)

Event Key	Parameters	Locality	Type	Description
`ace_attach_attached`	[_attachedObject, _itemClassname, _temporary]	Local	Listen	After an item was attached to a unit/vehicle. _temporary flag means a item is being re-attached after the player exits a vehicle
`ace_attach_detaching`	[_attachedObject, _itemName, _temporary]	Local	Listen	Just before an item gets detached/removed from a unit/vehicle. _temporary flag means its detached because the player unit entered a vehicle.

2.12 Trenches (`ace_trenches`)

Event Key	Parameters	Locality	Type	Description
`ace_trenches_placed`	[_unit, _trench]	Global	Listen	After trench object is placed by unit.
`ace_trenches_finished`	[_unit, _trench]	Global	Listen	After trench object is fully dug up by unit (100% progress).

2.13 Medical GUI (`ace_medical_gui`)

Event Key	Parameters	Locality	Type	Description
`ace_medical_gui_updateBodyImage`	[_ctrlGroup, _target, _selectionN]	Local	Listen	Allows mods to update any modifications they have made to the body image
`ace_medical_gui_updateInjuryListGeneral`	[_ctrl, _target, _selectionN, _entries]	Local	Listen	Allows mods to update the general injury list by pushing to the _entries array
`ace_medical_gui_updateInjuryListPart`	[_ctrl, _target, _selectionN, _entries, _bodyPartName]	Local	Listen	Allows mods to update the part injury list by pushing to the _entries array
`ace_medical_gui_updateInjuryListWounds`	[_ctrl, _target, _selectionN, _woundEntries, _bodyPartName]	Local	Listen	Allows mods to update the wounds injury list by pushing to the _woundEntries array
`ace_medical_gui_logListAppended`	[_ctrl, _row, _message, _unlocalizedMessage, _timeStamp, _arguments]	Local	Listen	After an entry is appended to the log list

2.14 Medical Treatment (`ace_medical_treatment`)

Event Key	Parameters	Locality	Type	Description
`ace_medical_treatment_fullHealLocalMod`	[_patient]	Local	Listen	Called before a local unit is fully healed, mods can listen and apply their own healing logic

2.15 Medical Status (`ace_medical_status`)

Event Key	Parameters	Locality	Type	Description
`ace_medical_status_getBloodLoss`	[_unit, _bloodLoss]	Local	Listen	Called when blood loss is calculated for a unit, mods can listen and modify the blood loss value by modifying the array

2.16 Interaction (`ace_interaction`)

Event Key	Parameters	Locality	Type	Description
`ace_interaction_doorOpeningStarted`	[_house, _door, _animations]	Local	Listen	Called when local unit starts interacting with doors
`ace_interaction_doorOpeningStopped`	[_house, _door, _animations]	Local	Listen	Called when local unit stops interacting with doors

2.17 Headless (`ace_headless`)

Event Key	Parameters	Locality	Type	Description
`ace_headless_groupTransferPre`	[_group, _HC (OBJECT), _previousOwner, _idHC]	Target	Listen	Called just before a group is transferred from any machine to a HC. Called where group currently is local and on the HC, where group is going to be local.
`ace_headless_groupTransferPost`	[_group, _HC (OBJECT), _previousOwner, _idHC, _transferredSuccessfully]	Target	Listen	Called just after a group is transferred from a machine to a HC. Called where group was local and on the HC, where group is now local. `_transferredSuccessfully` is passed so mods can actually check if the locality was properly transferred, as ownership transfer is not guaranteed.

3. Usage

Also Reference CBA Events System{:target="_blank"} documentation.

3.1 Adding / Removing Events

3.1.1 Add Event

CBA_fnc_addEventHandler - Adds an event handler with the event name and returns the event handler ID.

	Arguments	Type	Optional (default value)
0	Event name	String	Required
1	Code block	Code	Required
R	Event ID	Number	Return value

3.1.2 Remove Event

CBA_fnc_removeEventHandler - Removes a specific event handler of the given event name, using the ID returned from CBA_fnc_addEventHandler.

	Arguments	Type	Optional (default value)
0	Event name	String	Required
1	Event ID	Number	Required
R	None	None	Return value

3.2 Calling Events

3.2.1 Local Event

CBA_fnc_localEvent - Calls an event only on the local machine, useful for inter-module events.

	Arguments	Type	Optional (default value)
0	Event name	String	Required
1	Arguments	Any	Required
R	None	None	Return value

3.2.2 Target Event

CBA_fnc_targetEvent - Calls an event only on the target machine or list of target machines.

	Arguments	Type	Optional (default value)
0	Event name	String	Required
1	Arguments	Any	Required
2	Target(s)	Object OR Number OR Array	Required
R	None	None	Return value

3.2.3 Server Event

CBA_fnc_serverEvent - Calls an event only on the server machine (dedicated or self-hosted).

	Arguments	Type	Optional (default value)
0	Event name	String	Required
1	Arguments	Any	Required
R	None	None	Return value

3.2.4 Global Event

CBA_fnc_globalEvent - Calls an event on all machines - the local machine, and the server machine.

	Arguments	Type	Optional (default value)
0	Event name	String	Required
1	Arguments	Any	Required
R	None	None	Return value

3.3 Synchronized Events

3.3.1 Add Synchronized Event

Adds a globally synchronized event handler which will expire events after the provided time-to-live, or the code returns true.

ace_common_fnc_addSyncedEventHandler

	Arguments	Type	Optional (default value)
0	Event name	String	Required
1	Code block	Code	Required
2	Time to live	Number OR Code	Optional (default: `0`)
R	Event ID	Number	Return value

3.3.2 Remove Synchronized Event

Removes a specific event handler of the given event name, using the ID returned from ace_common_fnc_addSyncedEventHandler.

ace_common_fnc_removeSyncedEventHandler

	Arguments	Type	Optional (default value)
0	Event name	String	Required
R	None	None	Return value

3.3.3 Call Synchronized Event

Calls a globally synchronized event, which will also be run on JIP players unless it has expired. Event will expire after the provided time-to-live, or the code returns true.

ace_common_fnc_syncedEvent

	Arguments	Type	Optional (default value)
0	Event name	String	Required
1	Arguments	Any	Required
2	Time to live for this call	Number OR Code	Optional (default: `0`)
R	Event ID	Number	Return value

3.4 Example

// Event handler added on a target machine
["ace_interact_tapShoulder", ace_example_fnc_onTapShoulder] call CBA_fnc_addEventHandler;

// Event called on another machine (tapping above target machine)
["ace_interact_tapShoulder", [arguments], [target]] call CBA_fnc_targetEvent;

16 KiB Raw Blame History

1. Event Handlers

2. Events List

2.1 Fired Event Handlers (ace_common)

2.2 Medical (ace_medical)

2.3 Interaction Menu (ace_interact_menu)

2.4 Cargo (ace_cargo)

2.5 Captives (ace_captives)

2.6 Settings (ace_common)

2.7 Tagging (ace_tagging)

2.8 Explosives (ace_explosives)

2.9 Logistics Wirecutter (ace_logistics)

2.9 Refuel (ace_refuel)

2.10 Cook Off (ace_cookoff)

2.11 Attach (ace_attach)

2.12 Trenches (ace_trenches)

2.13 Medical GUI (ace_medical_gui)

2.14 Medical Treatment (ace_medical_treatment)

2.15 Medical Status (ace_medical_status)

2.16 Interaction (ace_interaction)

2.17 Headless (ace_headless)