Event Reference

Overview

Listening to ALiVE

ALiVE runs an internal event log. Every time a commander confirms an operation, a task is created, a resupply lands or a profiled unit is killed, ALiVE raises an event describing it. Your mission can register a listener against the event types it cares about and be called back whenever one of them fires, which lets mission scripts react to what ALiVE is doing without polling or reading its internals.

This page lists every event type ALiVE currently raises, along with the data each one carries, taken directly from the code that raises them. It is a reference for mission makers writing their own scripts. Nothing here is required to play or to build a mission in the editor.

How it works

Four things to know

1. Your listener is a hash carrying a class key that holds the name of your own function.
2. You register it against a list of event type names, and only those types reach you. Put "ALL" in the list to hear every event.
3. When a matching event fires, ALiVE calls your function with the operation handleEvent and the event itself. It runs in a scheduled thread of its own, one event at a time and in order, a moment after the event was raised.
4. Read the event with hashGet: type gives you the event name, data gives you the array described in the tables below, and message gives you the outcome on the replies that carry one.

Getting started

Registering a listener

// in initServer.sqf, after ALiVE has finished starting up
[] spawn {
    waitUntil {!isNil "ALiVE_REQUIRE_INITIALISED"};

    MyMission_fnc_opcomListener = compile preprocessFileLineNumbers "opcomListener.sqf";
    myListener = [nil, "create", ["MyMission_fnc_opcomListener"]] call MyMission_fnc_opcomListener;
};

And the listener itself:

// opcomListener.sqf
params ["_logic", "_operation", "_args"];
private "_result";

switch (_operation) do {

    case "create": {
        _args params ["_functionName"];

        private _logic = [[["class", _functionName]]] call ALiVE_fnc_hashCreate;

        private _listenerID = [
            ALiVE_eventLog,
            "addListener",
            [_logic, ["OPCOM_CAPTURE", "TACOM_ORDER_COMPLETE"]]
        ] call ALiVE_fnc_eventLog;

        [_logic, "listenerID", _listenerID] call ALiVE_fnc_hashSet;
        _result = _logic;
    };

    case "handleEvent": {
        private _event = _args;

        private _type = [_event, "type"] call ALiVE_fnc_hashGet;
        private _data = [_event, "data"] call ALiVE_fnc_hashGet;

        switch (_type) do {

            case "OPCOM_CAPTURE": {
                _data params ["_side", "_objective"];
                private _pos = [_objective, "center"] call ALiVE_fnc_hashGet;
                // react here
            };

            case "TACOM_ORDER_COMPLETE": {
                _data params ["_opcomID", "_objective", "_tacomState", "_side", "_factions", "_success"];
                // react here
            };
        };
    };
};

if (!isNil "_result") then {_result} else {nil};

Worked example

Pairing sector modules with ALiVE objectives

A common request. The commander events describe intent and orders rather than an objective quietly changing hands, so for ownership this reads control directly and keeps each sector in step with its nearest objective.

// Pairing Arma's Sector modules with ALiVE objectives.
// Place your sector modules in the editor and name them. For each sector this
// finds every commander's nearest objective, then hands the sector to the
// side whose commander holds its objective there. Run it on the server.

[] spawn {
    waitUntil {!isNil "ALiVE_REQUIRE_INITIALISED"};
    waitUntil {!isNil "OPCOM_instances" && {count OPCOM_instances > 0}};

    private _sectors = [sector1, sector2, sector3];   // your editor-placed modules
    private _pairs = [];

    // once: for each sector, each commander's closest objective
    {
        private _sector = _x;
        private _candidates = [];

        {
            private _side = [_x, "side", ""] call ALiVE_fnc_hashGet;
            private _objectives = [_x, "objectives", []] call ALiVE_fnc_hashGet;
            private _best = [];
            private _bestDist = 1e9;

            {
                private _centre = [_x, "center"] call ALiVE_fnc_hashGet;

                if (!isNil "_centre" && {count _centre > 1}) then {
                    private _d = _sector distance2D _centre;
                    if (_d < _bestDist) then {_bestDist = _d; _best = _x};
                };
            } forEach _objectives;

            // only an objective that is really at this sector
            if (_best isNotEqualTo [] && {_bestDist < 300}) then {_candidates pushBack [_side, _best]};

        } forEach OPCOM_instances;

        if (_candidates isNotEqualTo []) then {_pairs pushBack [_sector, _candidates]};

    } forEach _sectors;

    // then keep them in step
    while {true} do {

        {
            _x params ["_sector", "_candidates"];

            private _owner = sideUnknown;

            {
                _x params ["_side", "_objective"];
                if ([_objective, _side, 300, false] call ALiVE_fnc_isHeldObjective) exitWith {
                    _owner = [_side] call ALiVE_fnc_sideTextToObject;
                };
            } forEach _candidates;

            if (_owner isNotEqualTo sideUnknown) then {
                // hand _owner to your sector here
            };

        } forEach _pairs;

        sleep 30;
    };
};

Reference

Every event, and what it carries

46 event types, grouped by the module that raises them. The data column is the array you get back from the event's data key.

Worth knowing

Before you build on this

• Events are raised on the server. Register your listener on the server, and remote execute to clients yourself if they need to know.
• Register after ALiVE has started. Waiting on ALiVE_REQUIRE_INITIALISED before registering avoids the case where your listener attaches before the event log exists.
• If you want to mirror objective ownership onto something else, such as a sector module, polling suits it better than events. The commander events describe intent and orders rather than an objective quietly changing hands. The polling example above asks each commander about its own objectives.
• Two complete working listeners ship inside ALiVE, as opcomEventListener.sqf in the Hue Defence and Operation Cobra scenario missions. They are the same shape as the example above and are kept working alongside the code.

Alternative

Reading control without events

// Run on the server: OPCOM_instances only exists there.
// isHeldObjective asks whether an objective is still held and not overrun,
// from the side you name. It doesn't check who owns the objective, so ask it
// with the side of the commander the objective belongs to.
// The final false skips the stricter reserve-only test.

{
    private _side = [_x, "side", ""] call ALiVE_fnc_hashGet;
    private _objectives = [_x, "objectives", []] call ALiVE_fnc_hashGet;

    {
        if ([_x, _side, 300, false] call ALiVE_fnc_isHeldObjective) then {
            // this commander's side holds this objective right now
        };
    } forEach _objectives;

} forEach OPCOM_instances;

Changelog

Updates to this page

• 2026-10-27
  Checked against the current code. The polling and sector examples now ask each commander about its own objectives, since isHeldObjective doesn't check who owns one. Also corrected: the replies' outcome is in the message key, with every value listed; ATO_STATUS_REQUEST and ATO_CANCEL_REQUEST are listened for but not raised; TASK_UPDATE starts with the task's ID; listeners can take ALL and run one event at a time.
• 2026-08-12
  Every event ALiVE raises during a mission is now documented here, with the data each one carries, a listener you can copy, and a worked example for keeping sector modules in step with ALiVE objectives.