diff --git a/Mission-Maker-Function-Reference.md b/Mission-Maker-Function-Reference.md new file mode 100644 index 0000000..155890a --- /dev/null +++ b/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]; +```