Skip to content

Custom Events System

Jump to bottom
commy2 edited this page May 17, 2016 · 9 revisions

Custom Events System

What are custom events?

Custom events offer a way to manage your own events in a similar way to public variable events. However, the key thing is that they are easier to use and also manage events on a local level as well as remotely.

Custom events are never handled on JIP (Unless you are using CBA_fnc_globalEventJIP). That is, all events broadcast before a player joins are not handled, since they would be out-of-date. For state-changes, which you would want synced on JIP, use the standard publicVariable and addPublicVariableEventHandler commands instead.

Registering a handler for custom events

Generating custom events

  • CBA_fnc_localEvent: Generate an event which will be handled on only the local machine.
  • CBA_fnc_serverEvent: Generate an event which will be handled on only the server machine. The event will be executed in singleplayer mode.
  • CBA_fnc_globalEvent: Generate an event which will be handled on all machines, including the local one.
  • CBA_fnc_globalEventJIP: Generate an event which will be handled on all machines, including the local one. The event will also be executed on a client that joins in progress. The function returns an ID-string that can be used to overwrite the generated JIP-stack.
  • CBA_fnc_remoteEvent: Generate an event which will be handled on every other machine except the local one. The event will never be executed in singleplayer mode.
  • CBA_fnc_targetEvent: Generate an event which will be handled on all machines where at least one provided "target" is local. The targets can be objects and/or groups. The event will only be executed once per function call, even if multiple local targets are provided.

Parameter data type limitations

Only the following data types can be passed as arguments: <BOOLEAN>, <NUMBER>, <STRING>, <OBJECT>, <GROUP>, <TEAM_MEMBER>, <CODE> or <ARRAY>s consisting of any combination of these.

Naming custom events

Ensure that you use OFPEC tags in the naming of events, such as "MYTAG_barrelsExploded" if your tag was "MYTAG". This will prevent receipt of unexpected events from other users of the custom events system.

Using CBA's default events

CBA has a number of events that it routinely raises and any script can add a handler and deal with them.

  • (no default events documented yet)

Examples

MP sideChat

sideChat> is a command that only has an effect on clients, so rather than check whether we are on a client in the handler, it is best to only add handlers on client machines:

if (hasInterface) then {
    ["mySideChat", { (_this select 0) sideChat (_this select 1) }] call CBA_fnc_addEventHandler;
};

Later, we want everyone to see a sideChat message:

["mySideChat", [player, "Hello, nerds!"]] call CBA_fnc_globalEvent;

Running code without passing parameters

There is no requirement to pass parameters with the event. If no parameters are passed, then the receiving handler will not be passed _this.

Since we only want to create the vehicle on the server, it makes sense to only add a handler on the server:

if (isServer) then {
    ["mySummonUAZ", { "uaz" createVehicle (getMarkerPos "base") }] call CBA_fnc_addEventHandler;
};

Later, the player wants to create a UAZ (perhaps via an action) and runs:

["mySummonUAZ"] call CBA_fnc_globalEvent;

By broadcasting a global, rather than remote event, CBA guarantees that the server handles it, even if we are running as the MP host.

Service Bus

Using CBA's addEventhandler, globalEvent, localEvent, remoteEvent, serverEvent and targetEvent could be used to send localised messages to particular clients in the form of a service bus. This would assist in controlling communications between core and modules, and module to module comms.

Clone this wiki locally