Added mission maker's function refs

Mission-Maker-Function-Reference.md

@@ -0,0 +1,340 @@
+# Mission Maker Function Reference
+
+This page documents ARMATAK SQF functions that are useful from mission scripts. Function names follow the Arma 3 `call` convention:
+
+```sqf
+[arg1, arg2] call armatak_fnc_function_name;
+```
+
+Most functions send data immediately to TAK through the ARMATAK TCP extension. Positions can usually be passed as either an Arma object or an `[x, y, z]` position. ARMATAK converts the in-game map position to real-world coordinates before sending the CoT.
+
+## Quick Examples
+
+```sqf
+// Report an enemy tank at the object under the cursor for 1 hour.
+[cursorObject, "enemy", "tank", "Enemy Tank", "Observed near MSR"] call armatak_fnc_report_marker;
+
+// Draw a 300 m risk circle centered on a marker.
+private _pos = getMarkerPos "mortar_risk";
+[_pos, 300, "Mortar Risk Area"] call armatak_fnc_draw_circle;
+
+// Draw a route through editor markers.
+private _route = [
+    getMarkerPos "route_sp",
+    getMarkerPos "route_cp1",
+    getMarkerPos "route_vdo"
+];
+[_route, "Patrol Route Alpha"] call armatak_fnc_draw_route;
+```
+
+## Common Notes
+
+- Stale time values are in seconds. After that time, TAK clients may expire the item.
+- Colors are signed ARGB integers, as expected by ATAK drawing details. Defaults are usually white stroke and translucent fill.
+- Functions that call the extension assume the ARMATAK TCP socket/router is already configured and running.
+- 3DEN attributes can override callsigns, marker types, group colors, roles, and vehicle video URLs.
+
+## Reports and Markers
+
+### `armatak_fnc_report_marker`
+
+Sends a one-shot TAK report marker with its own stale time. This is the most useful function for scripted intelligence reports, trigger-created enemy sightings, objectives, and temporary points of interest.
+
+```sqf
+[_source, _affiliationOrType, _kind, _callsign, _remarks, _staleSeconds] call armatak_fnc_report_marker;
+```
+
+Supported affiliations are `"friendly"`, `"enemy"`, `"hostile"`, `"neutral"`, and `"unknown"`. You can also pass a raw CoT type starting with `a-`. Supported simple marker kinds are `"infantry"`, `"tank"`, `"car"`, `"apc"`, `"helicopter"`, `"plane"`, `"ship"`, and `"static"`.
+
+```sqf
+[cursorObject, "enemy", "tank", "Enemy Tank", "Reported enemy armor"] call armatak_fnc_report_marker;
+[screenToWorld [0.5, 0.5], "unknown", "infantry", "Unknown Contact", "Reported by patrol", 7200] call armatak_fnc_report_marker;
+[cursorObject, "a-h-G-U-C-A-T", "T-140 Angara", "Confirmed armor", 7200] call armatak_fnc_report_marker;
+```
+
+### `armatak_fnc_send_marker_cot`
+
+Sends a live marker CoT for an object using an explicit CoT type and callsign. It uses the object's current position, course, speed, UUID, and optional 3DEN video URL.
+
+```sqf
+[_unitOrVehicle, _cotType, _callsign] call armatak_fnc_send_marker_cot;
+[enemyTank1, "a-h-G-U-C-A-T", "Enemy Tank 1"] call armatak_fnc_send_marker_cot;
+```
+
+### `armatak_fnc_send_enemy_cot`
+
+Sends a marker CoT for a unit or vehicle using ARMATAK's automatic marker type and marker callsign extraction. Despite the name, the function uses the object's side and overrides to determine the CoT type.
+
+```sqf
+[_unitOrVehicle] call armatak_fnc_send_enemy_cot;
+{ [_x] call armatak_fnc_send_enemy_cot } forEach units enemyPatrol;
+```
+
+## Friendly Units and Groups
+
+### `armatak_fnc_send_eud_cot`
+
+Sends an EUD-style CoT for a unit with a callsign, group color/name, and group role. This is the lower-level function used by group sync.
+
+```sqf
+[_unit, _callsign, _groupName, _groupRole] call armatak_fnc_send_eud_cot;
+[player, "Alpha 1-1", "Blue", "Team Lead"] call armatak_fnc_send_eud_cot;
+```
+
+### `armatak_fnc_send_group_cots`
+
+Sends EUD CoTs for every unit in a group. ARMATAK derives each unit's callsign and role, and derives or assigns the group color.
+
+```sqf
+[_group] call armatak_fnc_send_group_cots;
+[group player] call armatak_fnc_send_group_cots;
+```
+
+```sqf
+[] spawn {
+    while {true} do {
+        [group alphaLead] call armatak_fnc_send_group_cots;
+        sleep 5;
+    };
+};
+```
+
+## Digital Pointer
+
+### `armatak_fnc_send_digital_pointer_cot`
+
+Sends a TAK digital pointer for a unit's current laser target. Nothing is sent if the unit has no active laser target.
+
+```sqf
+[_unit] call armatak_fnc_send_digital_pointer_cot;
+[player] call armatak_fnc_send_digital_pointer_cot;
+```
+
+## Drawing Tools
+
+### `armatak_fnc_draw_circle`
+
+Draws an ATAK Drawing Tools circle.
+
+```sqf
+[_center, _radius, _callsign, _staleSeconds, _strokeColor, _fillColor, _strokeWeight] call armatak_fnc_draw_circle;
+[player, 300, "Mortar Risk Area"] call armatak_fnc_draw_circle;
+[getMarkerPos "objective", 150, "OBJ Security Bubble", 10800] call armatak_fnc_draw_circle;
+```
+
+### `armatak_fnc_draw_ellipse`
+
+Draws an ATAK Drawing Tools ellipse or circle. Use it for support-by-fire areas, search areas, or oriented zones.
+
+```sqf
+[_center, _majorRadius, _minorRadius, _angle, _callsign, _staleSeconds, _strokeColor, _fillColor, _strokeWeight, _milsym, _cotType] call armatak_fnc_draw_ellipse;
+[screenToWorld [0.5, 0.5], 250, 100, 45, "Support by Fire"] call armatak_fnc_draw_ellipse;
+```
+
+### `armatak_fnc_draw_rectangle`
+
+Draws an ATAK Drawing Tools rectangle from a center point, width, length, and bearing.
+
+```sqf
+[_center, _width, _length, _bearing, _callsign, _staleSeconds, _strokeColor, _fillColor, _strokeWeight, _milsym] call armatak_fnc_draw_rectangle;
+[getMarkerPos "ea_center", 200, 500, 30, "Engagement Area"] call armatak_fnc_draw_rectangle;
+```
+
+### `armatak_fnc_draw_polyline`
+
+Draws an ATAK Drawing Tools freeform line or polygon from two or more positions or objects.
+
+```sqf
+[_points, _callsign, _closed, _staleSeconds, _strokeColor, _fillColor, _strokeWeight, _strokeStyle, _milsym, _cotType] call armatak_fnc_draw_polyline;
+[[pos player, screenToWorld [0.5, 0.5]], "Phase Line Blue"] call armatak_fnc_draw_polyline;
+```
+
+```sqf
+private _polygon = [
+    getMarkerPos "zone_1",
+    getMarkerPos "zone_2",
+    getMarkerPos "zone_3"
+];
+[_polygon, "Restricted Area", true] call armatak_fnc_draw_polyline;
+```
+
+### `armatak_fnc_draw_route`
+
+Sends an ATAK navigable route. The function creates route links, start point, final destination, and optional checkpoints along the route.
+
+```sqf
+[_points, _callsign, _staleSeconds, _color, _strokeWeight, _method, _routeType, _direction, _checkpointInterval] call armatak_fnc_draw_route;
+[[pos player, getMarkerPos "cp1", getMarkerPos "vdo"], "Patrol Route"] call armatak_fnc_draw_route;
+[_routePoints, "Convoy Route", 86400, -1, 4, "Driving", "Primary", "Infil", 2] call armatak_fnc_draw_route;
+```
+
+### `armatak_fnc_draw_tactical_graphic`
+
+Draws an ATAK shape with a MilSym tactical graphic overlay. Use this when the TAK symbol matters, such as axis of advance, boundaries, and other tactical graphics.
+
+```sqf
+[_points, _milsymSidc, _callsign, _closed, _staleSeconds, _strokeColor, _fillColor, _strokeWeight] call armatak_fnc_draw_tactical_graphic;
+[[pos player, screenToWorld [0.5, 0.5]], "GFGPOLAGM-----X", "Axis of Advance"] call armatak_fnc_draw_tactical_graphic;
+```
+
+## Registered CoTs and Cleanup
+
+### `armatak_fnc_register_cot`
+
+Registers a CoT UID under a mission-defined scope so it can be deleted later with `armatak_fnc_delete_registered_cots`. This is useful when scripts create persistent TAK objects and need to clean them up when an objective ends.
+
+```sqf
+[_scope, _uid, _cotType, _lat, _lon, _hae] call armatak_fnc_register_cot;
+private _registered = ["objective_alpha", _uid, "a-h-G-U-C-I", _lat, _lon, _hae] call armatak_fnc_register_cot;
+```
+
+Returns `true` when registration succeeds, otherwise `false`.
+
+### `armatak_fnc_delete_registered_cots`
+
+Sends forced delete CoTs for all registered CoTs in a scope, then removes them from the local registry.
+
+```sqf
+[_scope] call armatak_fnc_delete_registered_cots;
+private _deletedCount = ["objective_alpha"] call armatak_fnc_delete_registered_cots;
+systemChat format ["Deleted %1 TAK objects for objective_alpha", _deletedCount];
+```
+
+Returns the number of delete CoTs sent.
+
+## UAS and Video CoT
+
+### `armatak_fnc_send_drone_cot`
+
+Compatibility wrapper that sends UAS platform CoT for a drone. New scripts can call `armatak_fnc_send_uas_platform_cot` directly.
+
+```sqf
+[_drone] call armatak_fnc_send_drone_cot;
+[uav1] call armatak_fnc_send_drone_cot;
+```
+
+### `armatak_fnc_send_uas_platform_cot`
+
+Sends the UAS platform CoT for a drone, including callsign, position, course, speed, camera azimuth/elevation/FOV/range, flight state, controller UID, and optional video URL metadata.
+
+```sqf
+[_drone] call armatak_fnc_send_uas_platform_cot;
+```
+
+```sqf
+[] spawn {
+    while {alive uav1} do {
+        [uav1] call armatak_fnc_send_uas_platform_cot;
+        sleep 1;
+    };
+};
+```
+
+### `armatak_fnc_send_uas_video_cot`
+
+Publishes the UAS video feed CoT for a drone that has `armatak_attribute_marker_video_url` set. The function throttles refreshes and exits without sending if no video URL is configured.
+
+```sqf
+[_drone] call armatak_fnc_send_uas_video_cot;
+uav1 setVariable ["armatak_attribute_marker_video_url", "rtsp://192.168.1.50:8554/uav1", true];
+[uav1] call armatak_fnc_send_uas_video_cot;
+```
+
+### `armatak_fnc_send_uas_sensor_cot`
+
+Sends the UAS sensor CoT for a drone with a configured video URL. It links the sensor UID to the video UID and includes the sensor point of interest data derived from camera direction/range.
+
+```sqf
+[_drone] call armatak_fnc_send_uas_sensor_cot;
+[uav1] call armatak_fnc_send_uas_video_cot;
+[uav1] call armatak_fnc_send_uas_sensor_cot;
+```
+
+### `armatak_fnc_set_uas_camera_override`
+
+Overrides the camera data used by UAS CoT generation. Pass at least six values: azimuth, elevation, FOV, range, SPI ASL, and SPI geo. Pass an empty array to clear the override.
+
+```sqf
+[_drone, _cameraData] call armatak_fnc_set_uas_camera_override;
+
+private _spiAsl = getPosASL target1;
+private _spiGeo = (getPosATL target1) call armatak_client_fnc_convertClientLocation;
+[uav1, [120, -25, 45, 1800, _spiAsl, _spiGeo]] call armatak_fnc_set_uas_camera_override;
+
+[uav1, []] call armatak_fnc_set_uas_camera_override;
+```
+
+## Socket Control
+
+### `armatak_fnc_stop_tcp_socket`
+
+Stops the ARMATAK TCP socket if it is running and updates the mission namespace running flag. This is mainly useful for admin/debug scripts or mission cleanup logic.
+
+```sqf
+[] call armatak_fnc_stop_tcp_socket;
+```
+
+## Useful Extractors
+
+These helpers are useful when mission scripts need the same values ARMATAK uses internally.
+
+### `armatak_fnc_extract_unit_callsign`
+
+Returns the TAK callsign for a playable unit. It uses role description/name and can be overridden with the 3DEN `Unit Callsign` attribute.
+
+```sqf
+private _callsign = [player] call armatak_fnc_extract_unit_callsign;
+```
+
+### `armatak_fnc_extract_marker_callsign`
+
+Returns the TAK marker callsign for a vehicle, UAV, or object. It considers 3DEN `Marker Callsign`, vehicle variable name, display name, driver, UAV controller, and UAV connection state.
+
+```sqf
+private _callsign = [uav1] call armatak_fnc_extract_marker_callsign;
+```
+
+### `armatak_fnc_extract_role`
+
+Returns the CoT type/SIDC-like role ARMATAK will use for a unit or vehicle. It considers side, object type, vehicle type, and the 3DEN `Marker Type` override.
+
+```sqf
+private _type = [cursorObject] call armatak_fnc_extract_role;
+```
+
+### `armatak_fnc_extract_marker_video_url`
+
+Returns the video URL configured on a vehicle through the 3DEN `Video Feed URL` attribute or by setting `armatak_attribute_marker_video_url`.
+
+```sqf
+private _url = [uav1] call armatak_fnc_extract_marker_video_url;
+```
+
+### `armatak_fnc_extract_uuid`
+
+Returns the stable ARMATAK UUID used for a unit, vehicle, or object. Use it when you need to correlate scripted TAK objects with ARMATAK-generated CoTs.
+
+```sqf
+private _uid = [player] call armatak_fnc_extract_uuid;
+```
+
+## 3DEN Attributes for Mission Makers
+
+ARMATAK adds these editor attributes:
+
+| Scope | Attribute | Variable | Use |
+| --- | --- | --- | --- |
+| Unit | Unit Callsign | `armatak_attribute_unit_callsign` | Overrides EUD/unit callsign. |
+| Unit | Unit Role | `armatak_attribute_unit_role` | Sets the intended group role. |
+| Vehicle/Object | Marker Callsign | `armatak_attribute_marker_callsign` | Overrides marker or UAS callsign. |
+| Vehicle/Object | Marker Type | `armatak_attribute_marker_type` | Overrides CoT marker type. |
+| Vehicle/Object | Video Feed URL | `armatak_attribute_marker_video_url` | Adds a shared video URL for marker/UAS video CoTs. |
+| Group | Color | `armatak_attribute_group_color` | Sets TAK group color/name. |
+
+You can also set the same values from scripts:
+
+```sqf
+player setVariable ["armatak_attribute_unit_callsign", "Alpha 1-1 Actual", true];
+uav1 setVariable ["armatak_attribute_marker_callsign", "Raven 1", true];
+uav1 setVariable ["armatak_attribute_marker_video_url", "rtsp://192.168.1.50:8554/raven1", true];
+```