Capabilities

terrain is case-insensitive. Examples: 'Caucasus', 'PersianGulf', 'Syria', 'MarianaIslands', 'Nevada', 'Normandy', 'TheChannel', 'SinaiMap', 'Kola', 'Afghanistan', 'GermanyCW', 'Iraq'.

The session ID returned here is required by every other tool in this server. Sessions live in memory until close_miz is called or the server exits -- save_miz does NOT close the session.

Atomic write (temp file + rename). If path is omitted, saves back to the path it was opened from. Required for new_miz sessions (no source path).

Unsaved changes are lost.

Useful as a first call when opening an unfamiliar .miz -- gives an overview of who/what is present without listing every group. Returns: theater -- terrain class name (e.g. "Caucasus") start_time -- ISO 8601 datetime string (UTC) briefing -- {description, blue_task, red_task} (first 200 chars each) groups -- {blue: {plane, helicopter, vehicle, ship, static}, red: {...}, neutral: {...}} (counts per category) zones -- number of trigger zones triggers -- number of trigger rules weather -- {name, visibility_m, wind_ground_ms, wind_ground_dir, clouds_preset, clouds_density, fog, dust}

Checks performed: 1-3 Trigger condition cross-refs (missing group / unit / zone IDs) 4 Trigger action cross-refs (missing groups, units, zones, resources) 5 Goal condition cross-refs 6 Trigger sanity (conditions-less trigger fires every frame) 7 Vehicle group terrain slope (uses slope_threshold_deg) 8 Vehicle group surface type (water check) 9 Terrain data availability 10 Flight group route: no waypoints 11 Flight group route: single waypoint only 12 Flight group route: takeoff/landing missing airdrome_id 13 AI-only mission (no player or client slots) 14 Empty mission 15 Duplicate group IDs 16 Waypoint lock-state invalid (route has no ETA-locked anchor, OR a waypoint has both ETA_locked=False and speed_locked=False without ETA-locked brackets; DCS ME rejects the save) 17 Flight with no meaningful tasking (takeoff->land anchors only) 18 Ground-start flight with no Landing waypoint (no RTB point) 19 Flight with empty pylons on all units (info; tankers/AWACS exempt) 20 AI flight with a real route but no attack/engagement tasking (info; tankers/AWACS exempt) 21 Mission has no briefing description set (info) 22 Refueling type mismatch: boom-receptacle or probe-equipped aircraft present but no compatible tanker type (info) 23 Tanker/AWACS comms collision: two support aircraft share the same primary radio frequency (info) 24 Ground-group route surface: a vehicle group's waypoint sits over water, or a leg crosses water between two dry waypoints (warning; ground groups only -- flights/ships exempt; warn-not-block so amphibious crossings/bridges still save; uses the baked .dat, skips with an info note if the theater is not baked) detail: "summary" returns only issues + stats. "full" additionally includes decoded trigger list, group list, and goal list. slope_threshold_deg: slope (in degrees) above which a vehicle group placement is flagged (default 10.0, matching the Phase 9 placement tools). Trigger indices in issues messages and in the full-mode triggers list are 0-based, matching add_trigger / modify_trigger / delete_trigger. Returns dict: verdict "clean" | "warnings" | "errors" | "empty_mission" theater theater name string detail echo of the detail parameter issues list of {severity, check, message} stats {group_count, unit_count, groups_by_category, trigger_count, zone_count, goal_count, resource_count} (full only): triggers list of {trigger_index, decoded} (0-based index) groups list of {id, name, category, coalition, unit_count} goals list of {side, index, score, conditions}

Returns {ok: bool, warnings: [...], errors: [...]}.

Intended to be consulted at the start of and during a mission-building task. Advisory only -- nothing here blocks, enforces, or prevents saving. Takes no arguments; returns pure static content. Returns a dict with: purpose -- what the guide is for how_to_use -- short instruction for working through the stages stages -- ordered list of {stage, title, questions} objects; each question has "q" (the question) and "why" (the failure mode if skipped) notes -- cross-cutting reminders

Reads the open source mission, runs mission_report findings analysis, and writes a separate .miz file with diagnostic drawings on the F10 map. The source mission (session_id) is NOT modified. All drawings go on the standard Author layer. DCS supports exactly five layer names {Red, Blue, Neutral, Common, Author}; custom-named layers cause the Mission Editor to crash on load. Category is indicated by drawing name prefix and color: GRP:/GRP_LBL: -- group markers, coalition-colored ROUTE:/WP:/WP_LBL: -- route polylines and waypoint markers PROB:/PROB_LBL: -- issue markers (red=error, amber=warning) ZONE:/ZONE_LBL:/TRIG_SUMMARY -- trigger zones and text summary output_path: where to write the diag .miz. If omitted, derived from the source path as <dir>/<basename>_diag.miz. Required if the source mission has never been saved. Issues with no map position are NOT drawn; they appear in the return value "notes" list so they are not silently lost. Returns: output_path path to the written diag .miz source_path source mission path (None if never saved) drawing_layer standard layer name all drawings were placed on drawing_count total drawings added findings_summary {verdict, error_count, warning_count} notes list of informational strings

Example paths: coalition.blue.country[0].plane.group[3] weather.clouds.density forcedOptions Returns the raw value (dict / list / scalar) at that path. A valid path that resolves to a falsy value (0, false, "", {}, []) returns that value normally; failures (missing key, out-of-range index, wrong index type) raise ValueError with the full path, the failing component, the failure type, and -- for the common [0] case -- a hint that DCS Lua tables are 1-indexed.

Supported top-level sections: weather -- clouds, wind, fog, visibility, dust, etc. forcedOptions -- cockpit indicators, G-effects, etc. triggers -- trigger zones (zones sub-key) groundControl -- ground control roles goals -- mission goals/conditions The path must start with one of those section names, e.g.: weather.enable_fog weather.clouds.density forcedOptions.cockpitStatusGreenMessages NOT supported (use typed tools instead): coalition.* -> list_groups / move_group / set_payload / etc. date / start_time / map -> not exposed here Values are JSON-typed: pass numbers as numbers, booleans as booleans, null as null. A read-back check reports if the write did not take effect (e.g., preset interference).

Exactly one of airdrome_id, air_start_position, or pad_group_id must be provided. Groups spawn with empty pylons. Use set_payload(unit_id, pylons) to arm units, or list_weapons(aircraft_type) to find valid CLSID strings. Returns {group_id, name, unit_ids, unit_names, allocated_parking, warnings}. warnings is a reserved list (currently always empty; kept for shape stability). allocated_parking is empty for air and pad spawns.

Behaves identically to add_plane_group but draws from the helicopter catalog and uses a lower default air-start altitude (500 m vs 3 000 m). Exactly one of airdrome_id, air_start_position, or pad_group_id must be provided. Groups spawn with empty pylons. Use set_payload(unit_id, pylons) to arm units, or list_weapons(aircraft_type) to find valid CLSID strings. Returns {group_id, name, unit_ids, unit_names, allocated_parking, warnings}. warnings is a reserved list (currently always empty; kept for shape stability). allocated_parking is empty for air and pad spawns.

coalition: "blue" | "red" | "neutral" country: DCS country name -- must exist in the mission ship_type: DCS type string, e.g. "PERRY", "TICONDEROG", "KUZNECOW" Use list_unit_types(category="ship") to find valid ids. name: group name (must be unique in the mission) position: spawn position -- {lat_lon: {lat, lon}} or {xy: {x, y}} count: number of ships in the group (1-inf) heading: initial heading in degrees (0 = north; default 0) speed_knots: initial transit speed in knots (default 10); sets speed on the first waypoint. Add further waypoints via add_waypoint or set_route. skill: "average" (default) | "good" | "high" | "excellent" | "random" Returns {group_id, name, unit_ids, unit_names, lat, lon}.

coalition: "blue" | "red" | "neutral" country: DCS country name -- must exist in the mission vehicle_type: DCS type string, e.g. "M-1 Abrams", "ZSU-23-4 Shilka" Use list_unit_types(category="vehicle") to find valid ids. name: group name (must be unique in the mission) position: spawn position -- {lat_lon: {lat, lon}} or {xy: {x, y}} clear_trees: tri-state tree-clearing at the spawn footprint. None (default) clears only when the group qualifies (air-defence / radar units); True forces a clear regardless of type; False never clears. A clear wires one trees-only RemoveSceneObjects trigger zone around the group. count: number of vehicles (1-inf, DCS handles large groups) heading: initial heading in degrees (0 = north, 90 = east; default 0) formation: "line" (default) | "star" | "rectangle" | "scattered" | "vee" Controls initial vehicle spacing at spawn. move_formation: "offroad" (default) | "onroad" "onroad" makes AI follow roads; "offroad" cuts cross-country. skill: "average" (default) | "good" | "high" | "excellent" | "random" terrain_check: validate slope at the spawn point (default true). Raises ValueError if slope exceeds slope_threshold_deg. Pass false to skip (e.g. for wrecks or deliberate steep placement). slope_threshold_deg: slope limit in degrees for terrain_check (default 10). Returns {group_id, name, unit_ids, unit_names, lat, lon} plus a "terrain" key when terrain_check=True. The "tree_clear" key carries the wired clear ({zone_id, zone_name, radius, trigger_index}) or null when no clear happened. Route starts with one waypoint at the spawn position. Add further waypoints via add_waypoint or set_route.

Returns the new group id, unit id, name, and position, plus a "terrain" key when terrain_check=True.

Mirrors the DCS ME's one-click "add unit": clones the group's LAST unit verbatim (type, skill, livery, payload, radio preset blocks, frequency, heading, flags) and changes only what must differ -- a fresh mission-wide unit id, an incremented name, and a deconflicted placement (plus, for aircraft, an incremented callsign and tail number). The route, group-level task, and group frequency are group-level and are NOT touched. Applies to plane, helicopter, vehicle, and ship groups. Static groups are not supported (use add_static). group_id: the group to grow (from list_groups / add_*_group). count: how many units to add (default 1). Each is deconflicted against the previous one. Optional per-unit overrides (omitted => cloned / auto): parking_ids: pin specific parking crossroad_idx values for airbase aircraft (one per added unit, in order); else free spots are auto-allocated. Loud error if a pinned spot is taken or invalid. position: override placement (ground vehicle / ship / air-start aircraft) -- {lat_lon:{...}} or {xy:{...}}. Not valid for airbase aircraft (parking drives the position). skill: per-unit skill (same vocabulary as the create tools; "Client"/"Player" valid only for flyable airframes). payload: {pylon_number: clsid} for aircraft (validated; rejects invalid assignments). Omitted => cloned from the source. livery: livery id for the added unit(s); "" reverts to default. callsign: display callsign name for added aircraft (western callsign nations only; ignored with a warning for numeric-callsign nations). name: explicit unit name; only valid with count=1. Aircraft spawned on a FARP/carrier pad (pad_group_id) are rejected: deck/pad spot placement cannot be verified offline. Add a separate flight with add_plane_group / add_helicopter_group(pad_group_id=...). Returns {group_id, group_category, added_unit_ids, added_unit_names, allocated_parking, positions, callsigns (aircraft), total_unit_count, warnings}.

New IDs are allocated for the group and its units. offset_position: if given, the clone is placed there (lead unit). Otherwise the clone is offset 500 m east (+y) of the source. Returns the new group_id and the IDs of the new units.

Pass only the fields to change. Called with no fields, this is a no-op that returns the group_id and an empty updated list without mutating the group.

Pass only the fields to change. Supported fields (all optional): fuel -- internal fuel in kg. Use get_unit to read the current value (default at spawn = 100% internal fuel, e.g. 1140 for AH-64D, ~5000 for F/A-18C). Multiply by a fraction for partial fuel: 70% = fuel * 0.7. flare -- flare count (0-99; default 60 for most aircraft) chaff -- chaff count (0-99; default 30 for most aircraft) gun -- gun ammo percentage (0-100; default 100) skill -- "Average" | "Good" | "High" | "Excellent" | "Random" for AI, or "Client" for a human-flyable slot. Case-insensitive on input; stored as canonical PascalCase. "Player" is accepted as an alias and normalized to "Client". "Client" requires a flying unit (Plane / Helicopter) on a human-flyable airframe; the transition also populates the unit's radio preset block. The reverse transition (Client -> AI) clears the radio block so the .miz matches what the ME writes for AI slots. livery_id -- livery string (use list_liveries to find IDs; empty string resets to default) name -- unit name (must be globally unique in the mission) heading -- facing direction in degrees (0 = north) Not supported here: pylons (use set_payload), position (use move_group). skill is validated BEFORE any field is applied, so a bad skill value leaves the unit untouched. Called with no fields, this is a no-op that returns the unit/group ids and an empty updated list. Returns {unit_id, group_id, updated: [field, ...]} plus the new values for each changed field.

All units in the group move by the same offset (their formation is preserved). If rotate_to_heading is given (degrees), the group is also rotated so the lead unit faces that heading.

coalition: 'blue' | 'red' | 'neutral' country: country name (e.g. 'USA', 'Russia') -- case-insensitive category: 'plane' | 'helicopter' | 'vehicle' | 'ship' | 'static'

Handy when you remember 'Huey' but not the exact name.

Returns groups sorted by distance (nearest first). Each entry includes all fields from list_groups plus distance_m. coalition / category: optional filters (same as list_groups). radius_m: search radius in metres (e.g. 50000 for 50 km).

category: 'plane' | 'helicopter' | 'vehicle' | 'ship' | 'static' Returns a list of {id, name} dicts. The 'id' field is the DCS type string -- use it in set_payload, add_group, etc. 'name' is a more human-readable label where available (often the same as id).

add_plane_group and the flight macros otherwise assign a clean rotating default (Texaco -> Arco -> Shell for tankers, etc.); use this to override. name: the callsign name. For tanker airframes it must be one of the tanker callsigns (Texaco / Arco / Shell); for AWACS airframes one of the AWACS callsigns (Overlord / Magic / Wizard / Focus / Darkstar). Case-insensitive on input; stored canonical-cased. An invalid name for a role-locked airframe raises with the full valid set listed. Any other airframe accepts any name but returns a warning that the value was not role-validated. flight: flight number -- the first visible digit (e.g. the "2" in "Shell 2-1"). Callsign field [2]. first_unit: the lead unit's number -- the second visible digit (the "1" in "Shell 2-1"). Increments by one per unit across the group (lead = first_unit, wingman = first_unit + 1, ...). Callsign field [3]. So set_group_callsign(name="Shell", flight=2, first_unit=1) on a 2-ship produces "Shell21" (lead) and "Shell22" (wingman). Does NOT modify the pilot name or the group name -- those are independent fields. Returns: { "group_id": int, "callsign_name": str, # canonical, case-corrected "flight": int, "first_unit": int, "units_updated": int, "previous_callsign": dict, # lead unit's prior block (snapshot) "warnings": list[str], }

patrol_pos1 / patrol_pos2: the two ends of the CAP race-track. max_engage_distance_m: radius (metres) in which the flight will engage air threats. count: number of aircraft in the flight (1-4 typically). See create_awacs_flight for common parameter documentation. NOTE: Payloads are not set by this tool -- use set_payload if needed.

NOTE: Payloads are not set by this tool -- use set_payload afterwards if needed. NOTE: Repeated calls may produce slightly different air-start positions. Returns group_id, unit_ids, waypoint count, and spawn details. When a callsign is applied, the return value also carries "callsign".

See create_awacs_flight for common parameter documentation. NOTE: Payloads are not set by this tool -- use set_payload if needed.

target_position: lat/lon or xy of the SAM/AAA threat to suppress. max_engage_distance_m: engagement radius for radar-emitting targets. Route: spawn -> IP (30 km from target, random +/-15deg offset) -> SEAD WP at target -> fence-out WP on far side -> RTB (if ground-started). NOTE: The IP bearing has +/-15deg random variation -- repeated calls differ slightly. NOTE: Payloads are not set -- use set_payload after creation (SEAD loadout needed).

target_unit_id: the unit_id of the ground unit to strike. Must be a live unit (not a static object -- use target_position with sead_flight for statics). Route: spawn -> IP -> strike WP on unit -> fence-out WP -> RTB (if ground-started). NOTE: The IP bearing has +/-15deg random variation -- repeated calls differ slightly. NOTE: Payloads are not set -- use set_payload after creation (strike loadout needed).

group_to_escort_id: the group_id of the flight to escort. Must be a plane or helicopter group (not vehicle or ship). The escort flight starts from airdrome_id (ground start) or 10 km behind the escorted group's first waypoint (air start). NOTE: Payloads are not set -- use set_payload if needed.

zone_id: the trigger zone that, when entered by the opposing coalition, activates this flight. The zone must already exist in the mission (use add_zone or list_zones to manage zones). airdrome_id: REQUIRED for intercept flights -- must be a ground start. late_activation: if True (default), the flight sits uncontrolled until the trigger fires. Recommended to keep True. NOTE: The random secondary patrol point means repeated calls don't produce identical route shapes. NOTE: Payloads are not set -- use set_payload if needed.

group_id: the existing plane/helicopter group to modify. IMPORTANT: This mutates the flight's route. The waypoint at index 0 gets a CAP task, and two more waypoints (the race-track ends) are appended. The flight is no longer in the same state as when it was created. patrol_pos1 / patrol_pos2: the two race-track endpoints.

group_id: the existing plane/helicopter group to modify. target_position: lat/lon of the SAM/AAA threat. IMPORTANT: Mutates the flight's route -- adds IP, SEAD, and fence-out waypoints. The IP bearing has +/-15deg random variation (repeated calls differ).

group_id: the existing plane/helicopter group to modify. target_unit_id: the unit_id of the ground unit to strike. IMPORTANT: Mutates the flight's route -- adds IP, strike, and fence-out waypoints. The IP bearing has +/-15deg random variation (repeated calls differ).

Redesigned from two ME ground-truth missions confirmed flying in sim. A troop lift is two-sided: the transport helicopter carries an Embarking (pickup) then a Disembarking (dropoff) task; each troop group carries an EmbarkToTransport (board) task. Disembark is HELI-SIDE ONLY -- there is no troop-side DisembarkFromTransport in a working AI lift. The geometry is load-bearing: the heli must land CLEAR of the troops (not on top of them) while both stay within the troops' embark radius. The troops teleport to their wait point on spawn; if the heli's landing spot is the same coordinate it balks. So this composer places the heli's pickup waypoint + Embarking point `landing_offset_m` away from `pickup_position` (toward the dropoff), within `pickup_radius`. It APPENDS a pickup and a dropoff waypoint to the heli's route (at real transit speed -- a 0-speed waypoint never flies), so the author only supplies the two positions. transport_group_id: the lifting helicopter group (must be a helicopter). troop_group_ids: the ground troops to lift (each must be a vehicle group; place them at `pickup_position` before calling). pickup_position: where the TROOPS wait (their EmbarkToTransport point). dropoff_position: where the lift unloads (the heli's Disembarking point). pickup_radius: troops' embark radius in metres (EmbarkToTransport zoneRadius, default 200). `landing_offset_m` must be less. landing_offset_m: how far the heli lands from the troops (default 100; must be < pickup_radius so troops can reach it). Offset is toward the dropoff. board_specific_unit: if true, the troops board this transport's airframe TYPE specifically (the ME's "specific transport" form -- selectedType, e.g. "UH-1H"), so a multi-type mission does not cross-load. Default false = board any transport. transit_speed_kmh: heli transit speed for the appended waypoints (default: the heli's established cruise, or 200 km/h). transit_altitude_m: altitude of the appended pickup/dropoff waypoints (default: the heli's last waypoint altitude, or 100 m). Returns a summary of the appended waypoints and wired tasks.

Flat parameters matching the house convention (add_vehicle_group / add_ship_group): position is a structured Position, the rest are flat optional scalars. (set_route, which replaces a whole route, still takes a LIST of WaypointSpec objects -- a list cannot be flattened.) index: 0-based insertion position. The waypoint currently at this index (and all following) will be shifted back by one. Examples for a 2-waypoint route [TakeOff(0), Land(1)]: index=1 -> inserts before Land -> [TakeOff, NEW, Land] index=-1 -> same as index=1 on any route length (always inserts before the last waypoint) index=None / omitted -> inserts before the terminal Landing/LandingReFuAr waypoint if one exists, preserving it as the last waypoint. If the route has no terminal landing waypoint the new waypoint is appended at the end. Indices >= route length append at the end. Returns the new waypoint dict plus updated route length, and a "warnings" list. For a GROUND (vehicle) group, a new waypoint placed over water adds a warn-only entry (placement still succeeds -- the same baked-.dat surface check as mission_report check 24; amphibious/bridge crossings are legitimate). Empty for flights, ships, unbaked theaters.

waypoint_index: 0-based index into the route (use get_route to see current indices). type -- waypoint type string (same values as add_waypoint; an unknown type raises listing the valid set) name -- display name for the waypoint altitude_m -- altitude in metres (BARO) speed_kmh -- airspeed / ground speed in km/h ETA_locked -- bool; at least one takeoff waypoint must be true for DCS to accept the route speed_locked -- bool airdrome_id -- int; required for takeoff/landing waypoint types (raises if the effective type is takeoff/landing and the waypoint has no airdrome_id, new or pre-existing) Not supported here: tasks (use add_task), position (delete + re-add via add_waypoint). Called with no fields, this is a no-op that returns the waypoint's current state without mutating it. Returns the updated waypoint dict.

Returns: { "group_id": int, "waypoint_count": int, "waypoints": [ {index, type, name, position, altitude_m, speed_kmh, eta, eta_locked, airdrome_id, ...}, ... ] }

Clears the existing route and rebuilds it from the given waypoints. Each waypoint is a WaypointSpec: { position: {lat_lon: ...} or {xy: ...}, altitude_m?, speed_kmh?, type?, name?, airdrome_id? } (Deliberate asymmetry: add_waypoint takes flat scalars because it adds a single waypoint; set_route takes a LIST of specs because a list of waypoints cannot be flattened into one call. Same per-waypoint validation -- unknown type / missing airdrome_id raise in both.) For flying groups the first waypoint is the start position -- use type "TakeOffParking" (cold), "TakeOffParkingHot" (hot), or "TakeOff" (runway), plus airdrome_id. Subsequent waypoints use "Turning Point". For ground/ship groups "Turning Point" works for all waypoints. At least one waypoint is required. The first waypoint is auto-locked (ETA_locked=true) when the supplied spec contains no time anchor, so the route is accepted by the DCS Mission Editor (which requires at least one ETA-locked waypoint per group). The return value reports this via "eta_auto_locked", and each waypoint dict in "route" carries its own "ETA_locked"/"speed_locked". Returns the new route as a list of waypoint dicts, plus a "warnings" list. For a GROUND (vehicle) group, each new waypoint over water adds a warn-only entry (placement still succeeds -- same baked-.dat check as mission_report check 24). Empty for flights, ships, unbaked theaters.

waypoint_index: 0-based index into the group's route points. task_type and params: "Orbit" -- hold pattern altitude_m (default 4000), speed_kmh (default 600), pattern ("RaceTrack" | "Circle", default "RaceTrack") "EngageGroup" -- engage a specific group group_id (required), visible (bool, default false) "Hold" -- hold current position (no params) "GoToWaypoint" -- jump to another waypoint to_index (required, 1-based waypoint number), from_index (optional) "EPLRS" -- enable datalink group_id (optional, defaults to owning group's id) "SetFrequency" -- set radio frequency frequency_mhz (default 133), modulation ("AM" | "FM", default "AM"), power (default 10) "RunScript" -- run an inline Lua script script (Lua string) "ROE" -- rules of engagement option value: 0=WeaponFree, 1=OpenFireWeaponFree, 2=OpenFire, 3=ReturnFire, 4=WeaponHold "ReactionOnThreat" -- threat reaction option value: 0=NoReaction, 1=PassiveDefense, 2=EvadeFire, 3=ByPassAndEscape, 4=AllowAbortMission "AlarmState" -- ground unit alarm state value: 0=Auto, 1=Green, 2=Red "OptRTBOnBingoFuel" -- return to base when bingo fuel is reached value (bool, default true) "OptRTBOnOutOfAmmo" -- return to base when out of the given weapon(s) value: weapon-type code (default 4294967295=All). Common codes: 0=NoWeapon, 4294967295=All, 805306368=Cannon, 2032=Bombs, 30720=Rockets, 268402688=Missiles, 264241152=AAM, 4161536=ASM, 131072=ATGM, 32768=ARM, 65536=Antiship, 268402702=Guided, 805339120=Unguided (one named code; OR-combined custom masks not supported here) "OptRadarUsing" -- radar emission policy value: 0=NeverUse, 1=UseForAttackOnly, 2=UseForSearchIfRequired, 3=UseForContinuousSearch (default) "OptECMUsing" -- ECM emission policy value: 0=NeverUse, 1=UseIfOnlyLockByRadar (default), 2=UseIfDetectedLockByRadar, 3=AlwaysUse -- Restrict-class options (all bool, default true; "true" = restricted) -- "OptRestrictAirToAirAttack" -- forbid air-to-air attacks value (bool, default true) "OptRestrictAirToGround" -- forbid air-to-ground attacks value (bool, default true) "OptRestrictAfterburner" -- forbid afterburner use value (bool, default true) "OptRestrictJettison" -- forbid stores jettison value (bool, default true) "OptJettisonEmptyTanks" -- jettison empty fuel tanks value (bool, default true) "OptRestrictTargets" -- restrict engageable target categories value: 0=AllUnits (default), 1=AirUnitsOnly, 2=GroundUnitsOnly "OptFormation" -- set the group's flight formation (flying groups only) formation (required string; the variant/side/size is part of the name, case/underscore/space-insensitive). Valid: Fixed-wing: LineAbreast/Trail/Wedge/EchelonRight/EchelonLeft/ FingerFour/SpreadFour each x {Close, Open, GroupClose}; WW2_BomberElement{Close,Open}, WW2_BomberElementHeightSeperation, WW2_FighterVic{Close,Open}, ModernBomberFormation{Close,Open}. Rotary (helicopter): RotaryWedge, RotaryColumn, RotaryEchelonRight/Left {Small,Medium,Large}, RotaryFrontRight/Left {Small,Medium}. Unknown formation -> error listing the full set. Applying to a non-flying (vehicle/ship/static) group -> error. "Invisible" -- set unit invisible to AI value (bool, default true) "Immortal" -- set unit immortal value (bool, default true) "ActivateICLS" -- carrier ICLS beacon channel (int, default 1), unit_id (optional) "ActivateLink4" -- Link-4 datalink beacon frequency_mhz (default 336), unit_id (optional) "ActivateACLS" -- automatic carrier landing system unit_id (optional) "DeActivateBeacon" / "DeActivateLink4" / "DeActivateACLS" turn the corresponding beacon off (no params). Natural as a triggered action (see add_triggered_action). Returns the updated waypoint dict (tasks list included).

Composition: 1 x p-19 s-125 sr -- Flat Face search radar (rear) 1 x snr s-125 tr -- Low Blow tracking radar (near rear) N x 5p73 s-125 ln -- Goa launchers in forward arc (default 4) No command post -- the S-125 has no CP unit type in DCS. launcher_count: number of launcher groups (default 4; range 1-6). terrain_check: validate slope at site centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {search_radar, tracking_radar, launchers: [...]}, lat, lon} plus "terrain" key when terrain_check=True.

Composition: 1 x RLS_19J6 -- P-14 "Tall King" search radar (far rear) 1 x RPC_5N62V -- Square Pair tracking/fire-control radar (mid rear) N x S-200_Launcher -- Gammon launchers in forward arc (default 4) No command post -- the S-200 has no CP unit type in DCS. launcher_count: number of launcher groups (default 4; range 1-6). Out-of-range values raise ValueError. terrain_check: validate slope at site centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {search_radar, tracking_radar, launchers: [...]}, lat, lon} plus "terrain" key when terrain_check=True.

Composition: 1 x Kub 1S91 str -- SURN search/tracking radar (rear-centre) 3 x Kub 2P25 ln -- TELARs in forward arc Optional: with_supply=True -- adds a Ural-375 logistics truck at the rear heading: degrees the site faces (threat direction). 0=north. spacing_factor: scales inter-unit distances (default 1.0 ~= 120-130 m). terrain_check: validate slope at the site centre (default true). Raises ValueError if slope exceeds slope_threshold_deg. slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {radar, launchers: [id, id, id]}, lat, lon} plus "terrain" key when terrain_check=True.

The Osa is a self-contained TELAR -- radar and missiles in one chassis. count: number of TELARs (default 2; range 1-6). terrain_check: validate slope at site centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {launchers: [...]}, lat, lon} plus "terrain" key when terrain_check=True.

Composition: 1 x S-300PS 64H6E sr -- Big Bird search radar (far rear) 1 x S-300PS 40B6M tr -- tracking/engagement radar (mid rear) 1 x S-300PS 54K6 cp -- command post (rear flank) 2 x S-300PS 5P85C ln -- launch vehicles (forward arc left) 2 x S-300PS 5P85D ln -- launch trailers (forward arc right) terrain_check: validate slope at site centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {search_radar, tracking_radar, command_post, launchers: [...]}, lat, lon} plus "terrain" key when terrain_check=True.

Composition: 1 x SA-11 Buk SR 9S18M1 -- Snow Drift search radar (far rear) 1 x SA-11 Buk CC 9S470M1 -- command/fire-control (near rear) 4 x SA-11 Buk LN 9A310M1 -- TELARs in forward arc terrain_check: validate slope at site centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {search_radar, command, launchers: [...]}, lat, lon} plus "terrain" key when terrain_check=True.

The Tor is a self-contained TELAR -- radar and missiles in one chassis. count: number of TELARs (default 2; range 1-6). terrain_check: validate slope at site centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {launchers: [...]}, lat, lon} plus "terrain" key when terrain_check=True.

The 2S6 Tunguska is a self-contained gun/missile SHORAD vehicle. count: number of vehicles (default 2; range 1-4). terrain_check: validate slope at site centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {launchers: [...]}, lat, lon} plus "terrain" key when terrain_check=True.

Composition: 1 x Patriot str -- AN/MPQ-65 search/track radar 1 x Patriot ECS -- engagement control station 1 x Patriot AMG -- antenna mast group 1 x Patriot EPP -- electric power plant 1 x Patriot cp -- battery command post 4 x Patriot ln -- M901 launcher stations in forward arc terrain_check: validate slope at site centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {radar, ecs, amg, epp, command_post, launchers: [...]}, lat, lon} plus "terrain" key when terrain_check=True.

Composition: 1 x Hawk sr -- AN/MPQ-50 pulse search radar (far rear) 1 x Hawk cwar -- AN/MPQ-55 CWAR (continuous-wave acquisition, rear) 1 x Hawk tr -- AN/MPQ-46 HPI tracking radar (near rear) 1 x Hawk pcp -- battery control centre (rear) 3 x Hawk ln -- triple-rail launchers in forward arc terrain_check: validate slope at site centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {search_radar, cwar, tracking_radar, pcp, launchers: [...]}, lat, lon} plus "terrain" key when terrain_check=True.

Composition: 1 x NASAMS_Radar_MPQ64F1 -- AN/MPQ-64F1 Sentinel radar (rear) 1 x NASAMS_Command_Post -- fire-control (rear) 2 x NASAMS_LN_B -- launchers left arc 1 x NASAMS_LN_C -- launcher right arc terrain_check: validate slope at site centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {radar, command_post, launchers: [...]}, lat, lon} plus "terrain" key when terrain_check=True.

The IRIS-T SLM is a modern German medium-range air-defence system using the IRIS-T air-to-air missile in a surface-launched configuration. Range ~40 km, ceiling ~20 km -- between SHORAD and strategic SAMs. Composition: 1 x CHAP_IRISTSLM_STR -- search/tracking radar (rear) 1 x CHAP_IRISTSLM_CP -- command post (rear, offset from radar) N x CHAP_IRISTSLM_LN -- launchers in forward arc (default 3) launcher_count: number of launchers (default 3; range 1-4). Out-of-range raises ValueError. terrain_check: validate slope at site centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {radar, command_post, launchers: [...]}, lat, lon} plus "terrain" key when terrain_check=True.

Composition: 1 x Roland Radar -- acquisition radar (rear) 2 x Roland ADS -- fire units (launcher + own radar; forward arc) terrain_check: validate slope at site centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {radar, launchers: [...]}, lat, lon} plus "terrain" key when terrain_check=True.

The Rapier FSA is a British short-range air-defence system with both radar and optical tracking. The Blindfire radar provides all-weather engagement; the optical tracker enables emissions-controlled or ECM-resistant operation. Each launcher carries four Rapier missiles. Composition: 1 x rapier_fsa_blindfire_radar -- DN181 Blindfire tracking radar (rear) 1 x rapier_fsa_optical_tracker_unit -- optical tracker (rear, offset) N x rapier_fsa_launcher -- Rapier launchers (forward arc; default 2) launcher_count: number of launchers (default 2; range 1-4). Out-of-range raises ValueError. terrain_check: validate slope at site centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {blindfire_radar, optical_tracker, launchers: [...]}, lat, lon} plus "terrain" key when terrain_check=True.

The HQ-7 is a short-range mobile SAM with a separate search radar and self-contained TELAR launchers. Each TELAR has onboard tracking, so no separate tracking radar is required (unlike the S-125 / SA-3). Composition: 1 x HQ-7_STR_SP -- search radar (rear) N x HQ-7_LN_SP -- TELAR launchers in forward arc (default 4) launcher_count: number of TELARs (default 4; range 1-6). Out-of-range raises ValueError. terrain_check: validate slope at site centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {search_radar, launchers: [...]}, lat, lon} plus "terrain" key when terrain_check=True. Note: The HQ-7_LN_P (player-drivable) variant is intentionally not used by this macro; for player TELAR access use add_vehicle_group with vehicle_type="HQ-7_LN_P" directly.

radar_type: one of '55G6 EWR' (Soviet Tall King -- default) '1L13 EWR' (Soviet Box Spring) 'Dog Ear radar' (Soviet; short range, often used with SA-6) 'p-19 s-125 sr' (Soviet P-19 Flat Face) 'P14_SR' (Tall King -- SA-5 search radar; standalone EWR-capable) 'FPS-117' (AN/FPS-117 long-range EWR -- NATO) 'FPS-117 Dome' (AN/FPS-117 in a radome -- NATO long-range EWR) (The 'FPS-117 ECS' variant is the equipment control shelter, not a standalone radar -- detection_range 0 in the catalog -- so it is not offered here, same reason 'Patriot ECS' is not an EWR. Use add_vehicle_group for it directly if ever needed.) For a single EWR with no guard, add_vehicle_group(vehicle_type=<radar_id>) is the simpler path; this macro adds value primarily via with_guard and the role-keyed return shape. with_guard=True adds a ZSU-23-4 Shilka point defence vehicle. terrain_check: validate slope at site centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {radar, guard (optional)}, lat, lon} plus "terrain" key when terrain_check=True.

coalition: "blue" | "red" | "neutral". country: a DCS country in that coalition. name: unique group name (collision raises). position: pad centre (lat/lon or xy). farp_type: "SingleHeliPad" (default, one working pad), "FARP" (4-pad), or "InvisibleFARP". Unknown -> loud error listing the valid set. heading: pad heading in degrees (default 0). frequency_mhz: FARP ATC radio frequency (default 127.5). unlimited: if true (default), set the warehouse unlimited fuel / munitions / aircraft (the ME "unlimited" form). with_support: if true (default), place the coalition's ground-support vehicle set within 150 m (the functional-FARP requirement). with_statics: if true (default), also place the matching FARP statics (CP Blindage / Ammo Dump / Fuel Depot / Tent) by their vehicles. terrain_check / slope_threshold_deg: slope guard at the pad centre. The FARP is referenced two ways (there is no separate airdrome-space id -- FARPs do not appear in list_airfields): use the returned group_id for add_helicopter_group(pad_group_id=...) to spawn helis on the pad, and the returned farp_unit_id for get_warehouse / set_warehouse_properties / add_warehouse_supplier. Returns: {group_id, farp_unit_id, name, type, coalition, lat, lon, heading, frequency_mhz, warehouse:{unlimited flags}, support_vehicles:[], statics:[]} plus "terrain" when terrain_check.

Spawns the coalition's COMPLETE functional ground-support vehicle set -- the vehicles DCS requires within 150 m of a FARP for each service to work (rearm, refuel, ground power, repair, ATC/comms). Does NOT create the FARP pad itself: pair this with an existing pad, or use `create_farp`, which builds the pad + warehouse + this same vehicle set in one call. with_statics: also place the matching FARP role statics (default false; create_farp defaults them true). spacing_factor: scales the support ring radius (clamped to keep all vehicles within the 150 m service radius). terrain_check / slope_threshold_deg: slope guard at the cluster centre. Returns: {site_name, group_ids, unit_count, support_vehicles, statics, components:{aa?}, lat, lon} plus "terrain" when terrain_check.

Composition (coalition-aware): Blue: M1043 HMMWV scout -> HEMTT TFFT cargo trucks -> M1043 HMMWV rear Red: UAZ-469 scout -> KAMAZ Truck cargo trucks -> UAZ-469 rear Units are spaced along the heading axis (column formation). length: total number of trucks in the column (default 4; range 1-12). Scout and rear guard are added automatically. Add waypoints with add_waypoint after creation to set the route. terrain_check: validate slope at convoy centre (default true). slope_threshold_deg: slope limit in degrees (default 10). Returns: {site_name, group_ids, unit_count, components: {lead, cargo: [...], rear_guard}, lat, lon} plus "terrain" key when terrain_check=True.

Coalition-aware composition: Blue -- CVN_71 carrier + TICONDEROG cruiser + 2 x USS_Arleigh_Burke_IIa DDGs + PERRY frigate (screen) Red -- KUZNECOW carrier + MOSCOW cruiser + 2 x NEUSTRASH frigates + REZKY frigate (screen) Units are spread in a realistic formation around the carrier: Forward screen: 3 km ahead Port/starboard escorts: 3 km abeam Rear escort: 4 km astern spacing_factor scales all separations. speed_knots: initial transit speed for all ships (default 15). Returns: {site_name, group_ids, unit_count, components: {carrier, cruiser, escorts: [...], screen}, lat, lon} Note: verify ship type IDs with list_unit_types(category='ship').

trigger_type: "once" | "continuous" | "start" - "once" fires once when all conditions are true - "continuous" fires every frame while conditions are true - "start" fires once at mission start (ignores conditions) conditions: list of {type, params} dicts (all must be true for trigger to fire). group params accept "group_id" or "group"; unit params accept "unit_id" or "unit". Required params raise ValueError if missing. Time: {"type": "TimeAfter", "params": {"seconds": 60}} {"type": "TimeBefore", "params": {"seconds": 120}} {"type": "TimeSinceFlag", "params": {"flag": 1, "seconds": 30}} Flags: {"type": "FlagIsTrue", "params": {"flag": 1}} {"type": "FlagIsFalse", "params": {"flag": 1}} {"type": "FlagEquals", "params": {"flag": 1, "value": 5}} {"type": "FlagIsLess", "params": {"flag": 1, "value": 5}} {"type": "FlagIsMore", "params": {"flag": 1, "value": 5}} {"type": "FlagEqualsFlag", "params": {"flag": 1, "flag2": 2}} {"type": "FlagIsLessThanFlag","params": {"flag": 1, "flag2": 2}} Group/unit life: {"type": "GroupDead", "params": {"group_id": 42}} {"type": "GroupAlive", "params": {"group_id": 42}} {"type": "GroupLifeLess", "params": {"group_id": 42, "percent": 50}} {"type": "UnitAlive", "params": {"unit_id": 91}} {"type": "UnitDead", "params": {"unit_id": 91}} {"type": "UnitDamaged", "params": {"unit_id": 91}} {"type": "UnitLifeLess", "params": {"unit_id": 91, "percent": 50}} Group-zone: {"type": "PartOfGroupInZone", "params": {"group_id": 42, "zone_id": 1}} {"type": "AllOfGroupInZone", "params": {"group_id": 42, "zone_id": 1}} {"type": "AllOfGroupOutsideZone", "params": {"group_id": 42, "zone_id": 1}} {"type": "PartOfGroupOutsideZone","params": {"group_id": 42, "zone_id": 1}} Unit-zone: {"type": "UnitInZone", "params": {"unit_id": 91, "zone_id": 1}} {"type": "UnitOutsideZone", "params": {"unit_id": 91, "zone_id": 1}} {"type": "UnitInMovingZone", "params": {"unit_id": 91, "zone_id": 200, "zone_unit_id": 5}} {"type": "UnitOutsideMovingZone", "params": {"unit_id": 91, "zone_id": 200, "zone_unit_id": 5}} Coalition-zone (unit_type: "ALL"|"Air"|"Vehicle"|"Ship"|"Plane"|"Helicopter"): {"type": "AllOfCoalitionInZone", "params": {"coalitionlist": "blue", "zone_id": 1}} {"type": "AllOfCoalitionOutsideZone", "params": {"coalitionlist": "red", "zone_id": 1}} {"type": "PartOfCoalitionInZone", "params": {"coalitionlist": "all", "zone_id": 1, "unit_type": "Air"}} {"type": "PartOfCoalitionOutsideZone","params": {"coalitionlist": "blue", "zone_id": 1}} Unit altitude/speed/attitude: {"type": "UnitAltitudeHigher", "params": {"unit_id": 91, "altitude": 3000}} {"type": "UnitAltitudeLower", "params": {"unit_id": 91, "altitude": 3000}} {"type": "UnitAltitudeHigherAGL", "params": {"unit_id": 91, "altitude": 100}} {"type": "UnitAltitudeLowerAGL", "params": {"unit_id": 91, "altitude": 100}} {"type": "UnitSpeedHigher", "params": {"unit_id": 91, "speed": 200}} {"type": "UnitSpeedLower", "params": {"unit_id": 91, "speed": 200}} {"type": "UnitVerticalSpeedWithin", "params": {"unit_id": 91, "min_speed": -10, "max_speed": 10}} {"type": "UnitBankWithin", "params": {"unit_id": 91, "min_bank": -30, "max_bank": 30}} {"type": "UnitPitchWithin", "params": {"unit_id": 91, "min_pitch": -10, "max_pitch": 10}} {"type": "UnitHeadingWithin", "params": {"unit_id": 91, "min_heading": 0, "max_heading": 90}} Weapons/cargo in zone: {"type": "BombInZone", "params": {"zone_id": 1}} {"type": "MissileInZone", "params": {"zone_id": 1}} {"type": "SignalFlareInZone", "params": {"zone_id": 1, "color": 0}} {"type": "CargoUnhookedInZone", "params": {"cargo_id": 5, "zone_id": 1}} Airbase/helipad ownership: {"type": "CoalitionHasAirdrome","params": {"coalitionlist": "blue", "airdrome_id": 22}} {"type": "CoalitionHasHelipad", "params": {"coalitionlist": "blue", "helipad_id": 99}} Map/scoring: {"type": "MapObjectIsDead", "params": {"zone_id": 1}} {"type": "MissionScoreHigher", "params": {"coalitionlist": "blue", "score": 100}} {"type": "MissionScoreLower", "params": {"coalitionlist": "red", "score": 50}} {"type": "PlayerScoreLess", "params": {"scores": 50}} {"type": "PlayerScoreMore", "params": {"scores": 200}} Misc: {"type": "Random", "params": {"percent": 50}} {"type": "Or", "params": {}} Cockpit-state (training missions; no unit param -- cockpit-wide): {"type": "ArgumentInRange", "params": {"argument": 5, "min_value": 0.0, "max_value": 1.0}} {"type": "IndicationTextEqual", "params": {"indicator_id": 1, "element_name": "foo", "element_value": "bar"}} {"type": "CockpitHighlightVisible", "params": {"highlight_id": 1}} {"type": "CockpitParamEqual", "params": {"parameter": "param_name", "value": "1"}} {"type": "CockpitParamEqualToAnother","params": {"parameter": "p1", "parameter2": "p2"}} {"type": "CockpitParamInRange", "params": {"parameter": "p1", "min_value": 0.0, "max_value": 1.0}} actions: list of {type, params} dicts executed when trigger fires: {"type": "MessageToAll", "params": {"text": "...", "seconds": 10}} {"type": "MessageToBlue", "params": {"text": "...", "seconds": 10}} {"type": "MessageToRed", "params": {"text": "...", "seconds": 10}} {"type": "SetFlag", "params": {"flag": 1}} {"type": "ClearFlag", "params": {"flag": 1}} {"type": "IncreaseFlag", "params": {"flag": 1, "value": 1}} {"type": "DecreaseFlag", "params": {"flag": 1, "value": 1}} {"type": "SetFlagValue", "params": {"flag": 1, "value": 42}} {"type": "DoScript", "params": {"script": "trigger.action.outText(...)"}} {"type": "ActivateGroup", "params": {"group_id": 42}} {"type": "DeactivateGroup", "params": {"group_id": 42}} {"type": "Explosion", "params": {"zone": "ZoneName" | <zoneId int>, "altitude": 1, "volume": 1000}} {"type": "SetFlagRandom", "params": {"flag": 1, "min_value": 0, "max_value": 100}} F10 map markers (marker_id: unique int per mission, zone_id: int zone id): {"type": "MarkToAll", "params": {"marker_id": 1, "zone_id": 1, "text": "...", "comment": "...", "readonly": true}} {"type": "MarkToCoalition", "params": {"marker_id": 1, "zone_id": 1, "coalition": "blue", "text": "...", "comment": "..."}} {"type": "MarkToGroup", "params": {"marker_id": 1, "zone_id": 1, "group_id": 42, "text": "..."}} Radio menu (radiotext: display label, flag: set when item clicked, value: flag value): {"type": "AddRadioItem", "params": {"radiotext": "Call CAS", "flag": 5, "value": 1}} {"type": "AddRadioItemForCoalition", "params": {"coalition": "blue", "radiotext": "Call CAS", "flag": 5, "value": 1}} {"type": "AddRadioItemForGroup", "params": {"group_id": 42, "radiotext": "Rejoin", "flag": 6, "value": 1}} {"type": "RemoveRadioItem", "params": {"radiotext": "Call CAS"}} {"type": "RemoveRadioItemForCoalition","params": {"coalition": "blue", "radiotext": "Call CAS"}} {"type": "RemoveRadioItemForGroup", "params": {"group_id": 42, "radiotext": "Rejoin"}} Mission flow: {"type": "EndMission", "params": {"winner": "blue", "text": "Mission complete!"}} {"type": "LoadMission", "params": {"file": "missions/next.miz"}} AI control (group_id actions use int group id; unit_name actions use string unit NAME): {"type": "GroupAIOff", "params": {"group_id": 42}} {"type": "GroupAIOn", "params": {"group_id": 42}} {"type": "GroupStop", "params": {"group_id": 42}} {"type": "GroupResume", "params": {"group_id": 42}} {"type": "UnitAIOff", "params": {"unit_name": "Enfield 1-1"}} {"type": "UnitAIOn", "params": {"unit_name": "Enfield 1-1"}} {"type": "UnitEmissionOff", "params": {"unit_name": "SAM-1"}} {"type": "UnitEmissionOn", "params": {"unit_name": "SAM-1"}} {"type": "AITaskPush", "params": {"group_id": 42, "task_index": 1}} {"type": "AITaskSet", "params": {"group_id": 42, "task_index": 1}} Targeted messages: {"type": "MessageToCoalition", "params": {"coalition": "blue", "text": "...", "seconds": 10}} {"type": "MessageToCountry", "params": {"country": "USA", "text": "...", "seconds": 10}} {"type": "MessageToGroup", "params": {"group_id": 42, "text": "...", "seconds": 10}} {"type": "MessageToUnit", "params": {"unit_id": 91, "text": "...", "seconds": 10, "start_delay": 0}} Effects. For the five zone-effect actions below (Explosion above, IlluminatingBomb, SignalFlare, SceneryDestructionZone, ZoneIncrementResize) 'zone' accepts a zone NAME or an integer zoneId; the named zone must exist (it is resolved to its integer zoneId, which is what DCS stores -- confirmed vs the ME). ExplodeWPMarker is NOT ME-authorable, so its zone form is unconfirmed and left as a name string. unit_name is a string unit NAME: {"type": "ExplodeUnit", "params": {"unit_name": "SAM-1", "volume": 1000}} {"type": "ExplodeWPMarker", "params": {"zone": "ZoneName", "altitude": 1, "color": 0}} {"type": "ExplodeWPMarkerOnUnit","params": {"unit_name": "SAM-1", "color": 0}} {"type": "IlluminatingBomb", "params": {"zone": "ZoneName" | <zoneId int>, "altitude": 1}} {"type": "SignalFlare", "params": {"zone": "ZoneName" | <zoneId int>, "altitude": 1, "color": 0, "bearing": 0}} {"type": "SignalFlareOnUnit", "params": {"unit_name": "SAM-1", "color": 0, "bearing": 0}} Cargo / scenery: {"type": "SetInternalCargo", "params": {"cargo_mass": 500}} {"type": "FallInTemplate", "params": {"group_id": 42, "template": "template_name"}} {"type": "SceneryDestructionZone","params": {"zone": "ZoneName" | <zoneId int>, "destruction_level": 100}} {"type": "ZoneIncrementResize", "params": {"zone": "ZoneName" | <zoneId int>, "meters": 1000}} Returns the index of the new trigger in the trigger list and a summary.

trigger_index: 0-based index as returned by add_trigger. Must be in range. trigger_type: If provided, changes the trigger subclass ("once" / "continuous" / "start"). Conditions and actions are preserved unless also provided. comment: If provided, replaces the trigger comment. Otherwise preserved. conditions: If provided, FULLY REPLACES the existing condition list with the new list (same {type, params} format as add_trigger). Pass [] to clear all conditions. actions: If provided, FULLY REPLACES the existing action list with the new list. Pass [] to clear all actions. All fields are optional -- calling with only trigger_index is a no-op that returns the trigger's current state (useful for inspection). Validation is identical to add_trigger: unknown types and missing required params raise ValueError before any mutation occurs. Returns the same shape as add_trigger.

trigger_index: 0-based index as returned by add_trigger. Must be in range. WARNING: Deleting a trigger shifts all higher-indexed triggers down by one. If you need to delete multiple triggers, delete from highest index to lowest to avoid index confusion, or call get_raw_lua('trigrules') after each deletion to refresh your view of current indices. Returns metadata about the deleted trigger plus a renumbered flag that is True when any downstream triggers shifted (i.e. deleted trigger was not last).

Companion to add_task. Where add_task writes to a waypoint's task list (the task fires automatically when the group reaches that waypoint), add_triggered_action writes to the group's own task list (group.tasks[N]). A triggered action does NOT fire on its own -- it sits dormant until a trigger invokes it via an AITaskPush or AITaskSet action (see add_trigger), keyed by the 1-based task_index this tool returns. There is no waypoint_index parameter -- the action is attached to the group, not a route point. task_type and params are IDENTICAL to add_task -- the same task-type catalog, the same param shape and validation for each. See add_task's docstring for the per-type param reference. Supported task types: Orbit, AttackGroup, EngageGroup, EngageTargets, EngageUnit, EngageTargetsInZone, Follow, EscortTaskAction, RecoveryTanker, WWIIFollowBigFormation, FAC, FACEngageGroup, FACAttackGroup, Bombing, AttackUnit, AttackMapObject, FireAtPoint, Strafing, CarpetBombing, BombingRunway, SmokeCommand, SetUnlimitedFuelCommand, SetFrequencyForUnitCommand, SwitchWaypoint, StartCommand, StopTransmission, TransmitMessage, RunScriptFile, Embarking, Disembarking, EmbarkToTransport, DisembarkFromTransport, Land, CargoTransportation, ControlledTask, Hold, GoToWaypoint, EPLRS, SetFrequency, RunScript, ROE, ReactionOnThreat, AlarmState, OptRTBOnBingoFuel, OptRTBOnOutOfAmmo, OptRadarUsing, OptECMUsing, OptRestrictAirToAirAttack, OptRestrictAirToGround, OptRestrictAfterburner, OptRestrictJettison, OptJettisonEmptyTanks, OptRestrictTargets, OptChaffFlareUsing, OptDisparseUnderFire, OptRadioSilence, OptNoReportWaypointPass, OptEngageAirWeapons, OptAAMissileAttackRange, OptInterceptionRange, OptRadioUsageContact, OptRadioUsageEngage, OptRadioUsageKill, OptFormation, Invisible, Immortal, ActivateBeacon, ActivateICLS, ActivateLink4, ActivateACLS, DeActivateBeacon, DeActivateLink4, DeActivateACLS. Which types are NATURAL as triggered actions (commands / options you toggle on a trigger): SetFrequency, RunScript, EPLRS, ROE, ReactionOnThreat, AlarmState, OptRTBOnBingoFuel, OptRTBOnOutOfAmmo, OptRadarUsing, OptECMUsing, and the rest of the Opt* family (restrict-class, chaff/flare, radio usage, interception range, etc. -- see add_task for the full list), Invisible, Immortal, and the beacon family (ActivateBeacon / ActivateICLS / ActivateLink4 / ActivateACLS and their DeActivate counterparts -- e.g. switch a tanker's TACAN off when it leaves station). Which are UNUSUAL here (their natural home is a waypoint, but DCS still accepts them at group level and this tool does not block them): Orbit, AttackGroup, EngageGroup, EngageTargets, Hold, GoToWaypoint. GoToWaypoint in particular references route waypoint indices and is rarely meaningful as a triggered action -- allowed, but think twice. Only flying, vehicle, and ship groups have a triggered-action list. Static objects do not -- calling this on a static raises. Returns: { "group_id": int, "task_index": int, # 1-based position in group.tasks; pass this # to add_trigger's AITaskPush / AITaskSet # actions as "task_index" to invoke it "task_count": int, # total triggered actions now on the group "added_task": dict, # the written task (same shape as add_task's # "added_task") }

position: {lat_lon: {lat, lon}} or {xy: {x, y}} radius_m: zone radius in metres (default 1000) hidden: whether the zone is hidden in the ME (default false) color: optional RGBA dict {1: r, 2: g, 3: b, 4: a} with values 0.0-1.0. Defaults to white with 15% opacity if omitted. Returns the new zone's id, name, radius, and position.

Polygons in DCS are exactly 4-vertex quads, concave or convex. Self-intersecting (bowtie) quads are rejected as malformed. vertices: list of exactly 4 Position objects (lat_lon or xy form). Vertex order is preserved; centroid is computed automatically. hidden: whether the zone is hidden in the ME (default false) color: optional RGBA dict {1: r, 2: g, 3: b, 4: a} with values 0.0-1.0. Defaults to white with 15% opacity if omitted. properties: optional dict of user metadata {key: value}. Defaults to {}. Keys and values must be JSON-safe (strings, numbers, booleans, null). Returns the new zone's id, name, shape, type, vertices (xy and lat/lon), centroid (xy), color, and properties. Raises ValueError if: - vertices count != 4 - any vertex is unparseable (invalid Position) - quad is self-intersecting (bowtie)

Identified by zone_id (stable; never changes). Shape is immutable -- passing radius to a polygon zone or vertices to a circle zone is an error. To change shape, delete and re-create the zone. Parameters (all optional; only provided fields are applied): name: new name. Rename triggers a safety scan -- a few DCS constructs store the zone NAME as a string (ExplodeWPMarker; RadioTransmission stores its resolved name). If any reference the current name, the rename is refused with a clear error naming the references. (Conditions, Mark* actions, RemoveSceneObjects, and the five zone-effect actions Explosion / IlluminatingBomb / SignalFlare / SceneryDestructionZone / ZoneIncrementResize all reference the integer zoneId -- confirmed vs the ME, see Patch 12 -- and so are unaffected by a rename.) hidden: new hidden flag. color: RGBA dict {1: r, 2: g, 3: b, 4: a} with values 0.0-1.0. Fully replaces the existing color. properties: clean {key: value} dict. FULLY REPLACES the zone's property set -- to remove a property, omit it from the new dict. To merge, read current properties via list_zones, modify, then pass the full set back. Stored on-disk in DCS/ME's 1-indexed {key,value} table form (matches add_polygon_zone behaviour). radius: new radius in metres (CIRCLE ZONES ONLY). vertices: list of exactly 4 Positions (POLYGON ZONES ONLY). Same geometry validation as add_polygon_zone -- bowtie rejected, concave accepted. The centroid is recomputed automatically. zone_id is never changed. Returns the modified zone in the same shape as list_zones.

Safety: scans every construct that can reference a zone -- every trigger condition, every trigger action, every goal condition, and every CargoTransportation task -- for both integer-id references (self.zone == zone_id, used by conditions, Mark* actions, RemoveSceneObjects, and the five zone-effect actions Explosion / IlluminatingBomb / SignalFlare / SceneryDestructionZone / ZoneIncrementResize -- all id-referencing, confirmed vs the ME, Patch 12) AND string-name references (self.zone == the zone's current name, used by ExplodeWPMarker and RadioTransmission). The scan keys on the actual .zone value type (int vs str), so it stays correct regardless of which actions use ids. Behaviour: - If the zone is unreferenced, it is deleted cleanly. - If references exist and force=False (default), the deletion is refused with a clear error listing every referencing construct. - If force=True, the deletion proceeds and every now-orphaned reference is returned in the result so the damage is visible. Returns: {deleted: {id, name, shape, ...}, references_orphaned: [...]}

Returns for each zone: id, name, position, hidden (existing fields) type (int: 0=circle, 2=polygon), shape (str: "circle" or "polygon") radius (float for circles; 0 for polygons) color (RGBA dict {1: r, 2: g, 3: b, 4: a}, values 0.0-1.0) properties (user metadata dict {key: value}; {} if none) vertices (list of {x, y, lat, lon} points for polygons; null for circles)

zone_id must refer to an existing zone in the mission (use list_zones to find zone IDs and their radii). distance_to_center_m is always returned so callers can see how close to the zone edge a point is, regardless of inside/outside. Quad-point zones are not yet supported -- a clear error is raised if zone_id refers to one.

Maximum 100 points per call; raises ValueError if exceeded. Returns per-point results plus summary flags (all_inside, any_inside, inside_count) for quick branching without iterating the results list. Use case: "are any of this flight's waypoints inside the AO zone?" Quad-point zones are not yet supported.

side: "red", "blue", or "offline" (case-insensitive). The offline side is scored independently of coalitions -- useful for unconditional bonuses, trainer objectives, or single-player campaign scoring. rules: list of condition dicts -- SAME shape as add_trigger's conditions parameter. Every condition type supported by add_trigger works here verbatim, including Or for compound logic. All rules must evaluate true simultaneously for the goal to fire. Empty list is valid -- creates a placeholder goal that never fires. score: points awarded when all rules evaluate true. Negative values are valid; DCS supports scoring penalties. comment: human-readable label shown in the Mission Editor goals panel. Returns the new goal's 0-based index within its side's list.

side: the goal's CURRENT side ("red", "blue", or "offline", case-insensitive). goal_index: 0-based index within the current side's list. Optional update fields (omit any field to leave it unchanged): score: replace the goal's point value (negative values are valid). comment: replace the human-readable label. rules: FULL replacement of the condition list -- same shape as add_goal's rules parameter. Partial patches are not supported; supply the complete desired list or omit to keep existing rules. new_side: MOVE the goal to a different coalition side. The goal is removed from its current position and appended to the end of the destination side's list. The original goal_index is no longer valid after a move; moved_to_index in the return reports the new location. Calling with no update fields is a no-op that returns the goal's current state (useful for inspection -- matches modify_trigger behaviour). Probe-before-mutate: if rules validation fails, the original goal is left completely untouched. All validation runs before any field is modified.

side: "red", "blue", or "offline" (case-insensitive). goal_index: 0-based position within the side's goal list. Per-side renumbering: after deletion, all goals with a higher index on the SAME side shift down by 1. Goals on other sides are not affected. When deleting multiple goals from the same side, go highest-to-lowest to avoid index confusion (mirrors delete_trigger). renumbered: true if any goal on this side shifted (i.e. the deleted goal was not the last entry).

side: "red", "blue", or "offline" (case-insensitive). goal_index: 0-based position within the side's goal list. Use list_goals to see current indices. Returns side, goal_index, score, comment, rule_count, and the full rules list with each rule's predicate and params dict.

side: "red", "blue", or "offline" (case-insensitive). If omitted, all three sides are returned grouped under their side key. Each entry includes score, comment, and rule_count. Use get_goal for full rule detail on a specific goal.

DCS has no native "destroy X% of coalition" goal condition. This builds the standard ME-debuggable pattern: one triggerOnce per target group ({GroupDead} -> {IncreaseFlag +1}) feeding a shared counter flag, plus a goal {FlagIsMore flag, value=K-1} that fires when >= K groups are dead, K = ceil(percent/100 * N). side: who is SCORED by the goal -- "red" | "blue" | "offline". This is distinct from whose groups must die (that is the target below). percent: float in (0, 100]. Fraction of target groups that must die. Target selection -- provide EXACTLY ONE mode: - Enumerate: target_coalition ("red"|"blue"|"neutral"), optionally narrowed by categories (a list of "plane"|"helicopter"|"vehicle"| "ship"|"static"; default all). Counts all matching groups. - Explicit: group_ids = [ids...]. Counts exactly those groups (duplicates are de-duplicated). target_coalition/categories must be unset in this mode. counter_flag: optional int. Omitted -> an unused flag is auto-picked. Provided -> must not already be referenced by any trigger/goal (raises, naming where it is used). score: points awarded when the goal fires (default 100). comment: optional goal label (a descriptive default is generated). Each per-group trigger is tagged "attrition[<flag>]: <group> dead" so the scaffold is identifiable for inspection or removal. IMPORTANT -- build-time snapshot: N (the target count) and the threshold are fixed at call time. Run this AFTER all target groups are placed. Adding or deleting target groups afterward makes the threshold stale and can orphan a GroupDead trigger (mission_report checks 1-5 will flag it). Granularity is per-GROUP, not per-unit: a 4-ship counts as one. Re-running creates a second independent scaffold (no dedupe across calls). Returns: {goal_index, side, score, counter_flag, percent, n_target_groups (N), threshold_groups (K), target_groups: [{group_id, name}], trigger_indices: [...]}

Use case: ingress arrows, attack vectors, threat-axis indicators, SEAD run-in direction.

center: center of the circle (lat_lon or xy). radius_m: radius in meters (must be > 0). color: outline color {r,g,b,a}. Defaults to solid red. fill: fill color {r,g,b,a}. Defaults to transparent red (a=60). Use fill={r:0,g:0,b:0,a:0} for a fully transparent (outline-only) circle. Use case: SAM engagement envelope, trigger zone visualization, area-of-effect, safe/no-fly zone radius.

anchor: first vertex (also the drawing's anchor position). points: remaining vertices in order. Must have >= 2 entries so the polygon has >= 3 vertices total. The polygon is automatically closed (last vertex joins back to anchor). Use case: arbitrary AO shapes, irregular exclusion zones, complex kill-box polygons.

icon: one of the 9 standard icon names: "Mechanized", "MechanizedInfantry", "MechanizedInfantryWithFightingVehicle", "Recce", "Logistics", "MechanizedArtillery", "MechanizedRocketArtillery", "AirDefense", "SearchRadar" -- OR -- any filename string for custom icons placed in DCS's icon directory (passed through without validation). scale: size multiplier (must be > 0; 1.0 = default size). color: tint color. Defaults to solid red. Use case: off-map threat markers, friendly unit position symbols, FARP and airfield markers, key landmark indicators.

DCS renders this as a Bezier-like smoothed curve rather than hard straight segments. Visually similar to line_segments for <= 3 points but smoothed for longer paths. anchor: first control point; also the drawing's anchor. points: remaining control points (>= 1 entry required). closed: if True, the curve loops back to anchor. Use case: river outlines, coastlines, natural-looking route curves, engagement-zone boundaries that shouldn't look rigid.

layer: "Red", "Blue", "Neutral", "Common", or "Author". start, end: endpoints (lat_lon or xy). color: {r, g, b, a} with 0-255 values. Defaults to solid red. color_name: convenience shorthand -- one of "red", "blue", "green", "yellow", "orange", "white", "black", "magenta", "cyan". If both color and color_name are given, color wins. line_thickness: pixel width (default 8). line_style: "solid" (default), "dot", "dash", "dotdash", "cross", "square", "triangle", "wirefence", "dot2", "solid2", "strongpoint", "boundry1" through "boundry5". name: label in the ME drawing list. Use case: range fans, boundary lines, route legs.

anchor: first vertex; also the drawing's map anchor. points: remaining vertices in order. Must have >= 1 entry (so the polyline has at least 2 vertices total). closed: if True, the last vertex is connected back to anchor, producing a closed outline with no fill. For a filled closed shape use add_drawing_freeform_polygon instead. Use case: multi-leg route overlay, range boundary outline, perimeter.

p1, p2: the two centerline endpoints. The corridor runs from p1 to p2. radius_m: radius of the rounded caps AND half the corridor width (must be > 0). resolution: number of polygon segments per rounded cap (default 20; must be >= 3). Higher = smoother caps. Use case: navigation corridors, approach lanes, fly-zone tubes, safe-transit paths.

center: center point. radius_a_m: semi-major axis in meters (must be > 0). radius_b_m: semi-minor axis in meters (must be > 0). angle_deg: rotation of the major axis clockwise from north (0 = major axis points north, 90 = east). Use case: SAM seeker cone footprint, asymmetric AO, elongated threat envelope.

center: center of the rectangle. width_m: width in meters (must be > 0). height_m: height in meters (must be > 0). angle_deg: rotation clockwise from north (0 = sides run N/S and E/W, 45 = diamond orientation). Use case: kill boxes, training range boundaries, airspace blocks.

text: the label content (must not be empty). color: text color. Defaults to solid red. fill: box background color. Defaults to transparent red (a=60). Use fill={r:0,g:0,b:0,a:0} for no background. font_size: point size (must be > 0; default 20). font: font filename. DCS ships "DejaVuLGCSansCondensed.ttf" (default). Other fonts must exist in DCS's font directory; filenames are passed through without validation. border_thickness: box border width in pixels (default 2). angle_deg: text rotation clockwise from north (default 0 = normal). Use case: "PRIMARY TARGET", "IP ALPHA", "BULLSEYE", "DANGER -- SA-6 THREAT RING 24NM".

layer: one of "Red", "Blue", "Neutral", "Common", "Author". If None, all five layers are returned. Returns "layers" mapping each layer name to a list of drawing summaries with index, primitive_type, name, and anchor_position. Use the index with remove_drawing to delete a specific drawing. total_drawing_count covers all returned layers combined.

After removal, drawings at higher indices shift down by 1. Call list_drawings to confirm current indices before removing. renumbered: True if any remaining drawings shifted (i.e. the removed drawing was not the last one).

Other layers are unaffected. layer must be one of: "Red", "Blue", "Neutral", "Common", "Author". drawings_removed is 0 if the layer was already empty (no error).

Returns an overview of every airport and any pre-existing unit warehouses (FARPs, carrier ships, etc.). No new entries are synthesized. Args: session_id: Active session ID from open_miz. coalition: Optional filter: 'red', 'blue', or 'neutral' (case-insensitive). Pass None to list all coalitions. Returns: { "airport_count": int, "unit_warehouse_count": int, "airports": [ { "airdrome_id": int, "name": str, "coalition": str, "unlimited_fuel": bool, "unlimited_munitions": bool, "unlimited_aircrafts": bool } ], "unit_warehouses": [ { "unit_id": int, "name": str, "coalition": str, "unlimited_fuel": bool, "unlimited_munitions": bool, "unlimited_aircrafts": bool } ] }

Provide exactly one of airdrome_id or unit_id. If a unit_id is given and the unit has no warehouse entry yet, a default entry is synthesised in memory (not saved). The 'synthesized' flag in the response will be True in that case. Returns: { "warehouse_kind": "airport" | "unit", "airdrome_id": int | null, "unit_id": int | null, "name": str, "synthesized": bool, "warehouse": { ...all Warehouse fields... } }

The dict shapes must match what DCS expects: aircrafts: { "helicopters": { "OH58D": {"initialAmount": 4, "wsType": [1,2,6,332], "unlimited": false}, ... }, "planes": { ... } } weapons: { 1: {"wsType": [1,3,43,10], "initialAmount": 20}, 2: {"wsType": [1,3,43,103], "initialAmount": 10}, ... } If you pass 'aircrafts' and unlimited_aircrafts is currently True, the unlimited flag is automatically cleared and a warning is returned. Same for weapons / unlimited_munitions. All initialAmount values must be >= 0. Returns full warehouse state plus 'warnings: list[str]'.

Only fields that are provided (not None) are changed. All other fields retain their current values. Provide exactly one of airdrome_id or unit_id. Validation ranges: operating_level_air/fuel/equipment: 0-10 gasoline_init/methanol_mixture_init/diesel_init/jet_init: 0-100 periodicity, size: > 0 speed: > 0.0 Returns full warehouse state plus 'changed_fields: list[str]'.

Provide exactly one of airdrome_id/unit_id (the warehouse to edit) and exactly one of supplier_airdrome_id/supplier_unit_id (the supplier to add). The suppliers dict shape used by DCS: { 1: {"Id": <int>, "type": "airports"|"warehouses"}, ... } "airports" means the supplier is an airdrome; "warehouses" means it is a unit warehouse (FARP / carrier). Adding a duplicate supplier (same Id and type) is silently ignored. Returns full warehouse state plus 'added: bool'.

Provide exactly one of airdrome_id/unit_id (the warehouse to edit) and exactly one of supplier_airdrome_id/supplier_unit_id (the supplier to remove). Raises ValueError if the specified supplier is not present. Returns full warehouse state plus 'removed: bool'.

Reads DCS's own baked 100 m grid (land.getSurfaceType + land.getHeight), so the answer is authoritative and consistent with mission_report and the placement tools. There is NO coarse-dataset fallback (GSHHG has neither elevation nor surface subtype), so an unbaked/unknown theater or an out-of-grid point returns available:false with a reason -- never a guess. elevation_m is the BILINEAR-interpolated continuous ground height (the same basis as check_slope / get_elevation), while surface_type is the NEAREST cell's class -- different spatial bases, by design. surface_type uses DCS's real class names: LAND, SHALLOW_WATER, WATER, ROAD, RUNWAY (note SHALLOW_WATER, not "SHALLOW"). is_water is True for WATER or SHALLOW_WATER -- the same single-sourced convention is_water and mission_report use, so this tool can never contradict them. Returns (available): {available: True, surface_type: str, surface_code: int, elevation_m: float (signed), is_water: bool, x_m: float, y_m: float, source: "dat"} Returns (unavailable): {available: False, reason: "<theater> not baked" | "point outside terrain grid" | "unknown theater ..."} Raises: ValueError if position is in xy form, lacks lat_lon, or carries both.

Per-point version of sample_terrain. Each result carries its OWN available/reason: an in-grid point resolves while an out-of-grid point in the same batch returns available:false, both in one call (mirrors is_water_batch's per-point shape). See sample_terrain for the spatial-basis note (elevation bilinear / surface nearest-cell) and the no-fallback contract. Returns: {results: [<sample_terrain result>, ...]} -- same order as input. Raises: ValueError if a point is in xy form, lacks lat_lon, or carries both; the error identifies which index in the batch failed.

A pure readout of what the baked terrain crosses from start to end -- no modeling choices (no Earth curvature, no observer/target height; those belong to a line-of-sight tool). Useful for route planning, finding a lowest corridor, and "what do I cross between A and B". Reads DCS's baked 100 m grid (same source as sample_terrain / is_water), walking it vectorized in theater-XY: both endpoints are projected once, then the path is sampled in numpy -- so the per-sample answers AGREE with sample_terrain by construction (bilinear elevation, nearest surface). There is no GSHHG fallback; below-sea elevations clamp to 0. Returns (available): {available: True, theater, start:{lat,lon}, end:{lat,lon}, total_distance_m, step_m, native_sample_count, sample_count, coarsened: bool, reported_step_m, samples: [{dist_m, lat, lon, elevation_m, surface_type, is_water, in_grid}, ...], summary: {min_elevation_m, max_elevation_m, max_elevation_at:{dist_m,lat,lon}, mean_elevation_m, crosses_water, water_segments:[{from_dist_m,to_dist_m}], surface_composition:{<NAME>:count, ...}, any_out_of_grid}} Off-grid samples carry in_grid:false with null elevation/surface and count into summary.any_out_of_grid (per-sample honesty); a fully-off- grid theater-baked path stays available:true with null elevation stats. Returns (unavailable -- no walk possible): {available: False, reason: "<theater> not baked" | "unknown theater ..."} Raises: ValueError if a Position is xy-form / missing lat_lon / both, if step_m <= 0, or if max_samples < 2.

The third spatial primitive alongside sample_terrain (point) and terrain_profile (line): summarizes the baked terrain within radius_m of a center -- elevation min/max/mean/std (std = a ruggedness proxy), relief, highest/lowest point, and surface composition. LZ/FARP suitability and SAM siting compose this. Reads RAW per-cell values (the cells as baked), NOT bilinear -- zonal stats describe cells, not an interpolated surface. This agrees with sample_terrain by construction: bilinear AT a cell center returns that cell's node value, so a raw cell == sample_terrain's elevation at that cell center (to projection rounding). Surface classification uses the single-sourced is_water_surface convention. Returns (available): {available: True, theater, center:{lat,lon,ground_elevation_m}, radius_m, cells_in_grid, cells_total, partial_coverage: bool, elevation:{min_m,max_m,mean_m,std_m}, relief_m, highest_point:{lat,lon,elevation_m}, lowest_point:{lat,lon,elevation_m}, surface_composition:{<NAME>:count,...}, surface_fractions:{<NAME>:fraction,...}, water_fraction} Stats are over IN-GRID disc cells only; partial_coverage flags a disc that overlaps the grid edge (honest -- nothing past the edge invented). Returns (unavailable): {available: False, reason} for an unbaked/unknown theater or an off-grid center. Raises: ValueError on xy-form center, radius_m <= 0, or radius_m above the cap.

Answers: can an observer at A see a target at B over the BARE-EARTH terrain between them (no buildings, trees, or objects -- terrain masking, not full in-sim LOS), accounting for Earth curvature and atmospheric refraction? Built on the proven walk_path primitive (same projection + reads as sample_terrain / terrain_profile, so elevations agree by construction). Height semantics -- each endpoint takes height_m + height_ref: - "agl": height above the terrain at that point (eye_msl = ground + h). - "msl": absolute height above sea level (eye_msl = h; terrain ignored). Defaults are 0 m AGL / 0 m AGL (pure ground-to-ground intervisibility). Canonical tactical use: observer = radar antenna AGL (e.g. 15 m), target = aircraft altitude MSL (e.g. 9144 m). Both endpoints MUST be in-grid; an off-grid endpoint or unbaked theater -> available:false (cannot model terrain we cannot read). Model (over interior samples; endpoints are the eyes, excluded): R_eff = k_factor * 6371000 (k=4/3 standard atmosphere) bulge(s) = s*(D-s) / (2*R_eff) los_msl(s) = observer_eye + (target_eye - observer_eye)*(s/D) clear iff min(los_msl(s) - (terrain(s) + bulge(s))) >= 0 Returns (available, determinate): {available: True, theater, observer:{...,ground_elevation_m,eye_msl_m}, target:{...}, total_distance_m, k_factor, earth_radius_eff_m, step_m, samples_evaluated, clear: bool, min_clearance_m (signed), controlling_point:{dist_m,lat,lon,terrain_elevation_m,clearance_m}, los_indeterminate: False, any_out_of_grid: False, note: "bare-earth terrain masking; excludes buildings, trees, and objects"} Returns (indeterminate -- interior runs off-grid): clear: None, los_indeterminate: True, any_out_of_grid: True, + reason. (Never reports clear over terrain it cannot read.) Returns (unavailable): {available: False, reason} for an unbaked/unknown theater or an off-grid endpoint. Raises: ValueError on xy-form Position, an invalid height_ref, step_m <= 0, or k_factor <= 0.

From an emitter at center C (antenna height), against a target at altitude A, out to max_range_m: sweeps n_azimuths radials and reports, per azimuth, where the target is VISIBLE vs MASKED by BARE-EARTH terrain (plus Earth curvature + refraction). Turns a range ring into a real terrain-masked coverage diagram. HONEST LABEL: this is bare-earth terrain masking + a curvature horizon -- NOT radar power, RCS, beam pattern, or atmospheric attenuation. It says where line of sight exists, not where a real radar would detect. Composes the proven walk_path + viewshed sweep (provably equivalent to check_los at every sample). One walk + one cumulative-max pass per radial. Returns (available): {available: True, theater, center:{lat,lon,ground_elevation_m, antenna_msl_m}, target:{altitude_m,ref}, max_range_m, n_azimuths, k_factor, step_m, azimuths:[{azimuth_deg, max_visible_range_m, visible_segments:[{from_m,to_m}], masked: bool, indeterminate_beyond_m: float|null}, ...], summary:{azimuths_total, azimuths_full_coverage, azimuths_with_masking, azimuths_indeterminate, min_visible_range_m, mean_visible_range_m, max_visible_range_m, fully_clear: bool, any_indeterminate: bool}} Per-azimuth segments + scalars only (no per-step arrays). A radial that leaves the grid at range g carries indeterminate_beyond_m=g; nothing is reported visible beyond g (unknown != visible), distinct from masked. Returns (unavailable): {available: False, reason} for an unbaked/unknown theater or an off-grid center. Raises: ValueError on xy-form center, invalid height refs, n_azimuths out of [1,360], or non-positive target/range/k_factor/step.

Two data sources, reported via the "source" field: - source="dat": when a theater is named and its baked 100 m surface grid (DCS's own land.getSurfaceType) is available and covers the point. Authoritative and accurate near coastlines -- consistent with mission_report and the placement tools. WATER and SHALLOW both count as water. - source="gshhg": the coarse GSHHG coastline dataset (via global-land-mask) plus Black Sea / Caspian override polygons. Used when no theater is named, the theater is not baked, or the point is outside the baked grid. A few-km coastline resolution -- near-shore answers can be wrong (over-reports land). Returns: {is_water: bool, source: "dat" | "gshhg"} Raises: ValueError if position is in xy form, lacks lat_lon, or carries both.

Accepts the standard Position object in lat_lon form for each point. Mixed batches must all be lat_lon -- an xy-form point in the batch is rejected with a clear error. Water/land is answered from the baked .dat surface grid when a theater is named and can answer (source="dat", accurate near coasts), else from the coarse GSHHG path (source="gshhg"). The source is reported PER POINT: a point inside the baked grid resolves via the .dat while an out-of-bounds point in the same batch falls back to GSHHG, so the two can differ within one call. Returns: {results: [{is_water: bool, source: "dat"|"gshhg"}, ...]} -- same order as input. (Return shape changed from a bare [bool, ...] list to per-point objects when the source flag was added.) Raises: ValueError if a point is in xy form, lacks lat_lon, or carries both forms; the error identifies which index in the batch failed.

The scenery counterpart to find_land_near: spiral concentric rings (250 m steps) from the point to the nearest cell whose obstruction level is at most *max_level*. Useful when a spawn lands on/in a building. Reads the scenery sidecar only -- no fallback. Returns (available): {available: True, found: bool, lat, lon, distance_m, structure_count, level}. If the origin already satisfies max_level, found is True with distance_m 0 at the input point. If nothing qualifies within the radius, found is False (lat/lon = input, distance_m 0). Returns (unavailable): {available: False, reason} for an unbaked theater, absent sidecar, or an off-grid origin. Raises: ValueError on xy-form Position, an invalid max_level, or a sidecar co-registration mismatch.

Useful when a spawn coordinate has accidentally landed in the sea. Samples concentric rings at 250 m intervals; angular resolution scales so the worst-case gap between samples is ~10 % of the ring radius. Land/water at each sample is classified from the baked .dat when a theater is named and can answer (accurate near coasts), else from GSHHG. The "source" of the returned answer is reported. Returns: {found: bool, lat: float, lon: float, distance_m: float, source: "dat" | "gshhg"} distance_m is always <= max_radius_m (strictly enforced via haversine). If found is False, lat/lon equal the input and distance_m is 0. source reflects the dataset that classified the accepted land sample (or, when not found, the path used for the search). Note: on the GSHHG path coastline resolution is a few km, so sub-km offshore points may need max_radius_m > 2000.

Reads the scenery sidecar (<theater>_scenery.dat) -- a per-cell count of terrain structures (buildings/bridges/towers), co-registered to the terrain grid and harvested in-sim (see tools/bake_scenery). Lets placement avoid clipping units into buildings. Bare structures only -- NOT trees (engine-managed vegetation, not enumerable; use clear_scene_objects_in_zone to clear those at runtime). Graded level from the cell's structure count: "clear" (0), "light" (1-4, scattered), "heavy" (>=5, dense built-up). obstructed = count > 0; the level lets a caller choose strictness. Returns (available): {available: True, theater, structure_count: int, obstructed: bool, level: "clear"|"light"|"heavy", x_m, y_m} Returns (unavailable): {available: False, reason} for an unbaked theater, an absent scenery sidecar ("no scenery data for <theater>"), or a point out of grid. Raises: ValueError on xy-form Position, or a co-registration mismatch between the sidecar and the terrain .dat (loud -- a bad sidecar is worse than none).

Creates a TriggerStart (fires once, no conditions, at mission start) that carries a RemoveSceneObjects action targeting the named zone. IMPORTANT - tile quantization caveat: DCS applies RemoveSceneObjects at tile granularity (roughly 100 m). Objects near the zone boundary may be cleared even if they lie slightly outside the zone circle, and objects just inside the boundary in an adjacent tile may be missed. Place the zone center and radius with this in mind; for precise clearance add ~100 m to the desired radius. zone_id: Integer id of an existing trigger zone (as returned by list_zones or add_zone). The zone name is resolved internally -- you do not need to pass the name. objects_mask: Which objects to remove. One of: "trees_only" - vegetation only (safe; no structural damage) "objects_only" - man-made objects only (buildings, statics) "all" - trees AND man-made objects Default: "trees_only" comment: Optional label for the trigger rule as it appears in the ME trigger list. Defaults to "clear_<mask>_<zone_name>". Returns: trigger_index - 0-based position in the trigger list trigger_type - predicate string (always "TriggerStart") comment - the comment actually stored on the rule zone_id - the zone id that was resolved zone_name - the zone name passed to RemoveSceneObjects objects_mask - the normalised mask key ("trees_only" / "objects_only" / "all") objects_mask_value - raw DCS enum integer (0=ALL, 1=TREES_ONLY, 2=OBJECTS_ONLY)

Returns [{id, name, lat, lon, parking_total, runways}] for every airport in the terrain. The id field is the airdrome_id you pass to add_plane_group, add_waypoint (Landing/TakeOff types), etc. Helipad-only sites (FARPs etc.) are not included here -- they show up in list_parking_spots filtered to helicopter=True slots.

Returns [{name, heading, id, main}] for each runway. heading is in degrees; name is the runway designator e.g. "22-04".

Returns slots that helicopters can use (helicopter=True). Many airfields have heli spots mixed in with fixed-wing ramps; this filters to just those. Each entry: {parking_id, slot_name, free, large, lat, lon}

Each slot: {parking_id (crossroad_idx), slot_name, free, airplanes, helicopter, large, shelter, lat, lon} Pass parking_id values to add_plane_group's parking_ids to override auto-allocation.

and post-write coverage reporting. pylons: {pylon_number: clsid}. Use list_weapons(unit_type) to discover valid pylon numbers and CLSIDs for an airframe. force: if True, write the payload even if validation fails. The rejected assignments are returned under "validation_warnings" so deviations are visible, not silent. Default False rejects the call without writing anything when validation fails. Semantics: MERGE -- pylons not mentioned in the call are left unchanged on the unit. To clear a pylon, pass an empty string as the CLSID (always valid, never flagged). Validation runs in one pass and collects every invalid assignment. Three distinct failure modes: - "invalid_pylon": the pylon number doesn't exist on the airframe. - "clsid_unknown_for_airframe": the CLSID isn't recognized on ANY pylon of this airframe (typo, mod store, etc.). - "clsid_not_on_this_pylon": the CLSID is valid for the airframe but not on the requested pylon (the error message lists the pylons where it is valid). Returns: { unit_id, type, pylons: <final unit.pylons after the write>, coverage: {filled: [...], empty: [...]}, validation_warnings?: [...] -- only present when force=True wrote assignments that failed validation. } Coverage reflects the unit's actual pylon state AFTER the write -- so merged-in pylons from earlier set_payload calls are counted too. An empty coverage.empty means a fully-armed airframe; a non-empty list is informational, never a rejection (partial loadouts are legitimate).

unit_id: the unit to arm; its aircraft type is read from the unit. role: required. Canonical task name, display alias, or numeric task id. loadout_name_contains: optional case-insensitive substring filter, matched against EITHER the loadout's displayName OR its name field. Some airframes (e.g. F-5E-3, A-10C, FA-18C) ship loadouts with no displayName, carrying the descriptive text only in name; others (e.g. F-16C) populate both identically. Searching both fields handles every case. Use to narrow the pick when a role has several loadouts (e.g. "AIM-120C" to prefer a C-model CAP loadout). Looks up the unit's aircraft type, reads the matching UnitPayloads file(s), filters by role (then by the optional substring), picks the FIRST match, and applies it via set_payload's write+validation path (merge semantics, same as a hand-built set_payload call). The DCS-canonical loadouts validate cleanly; if a loadout carries a CLSID set_payload rejects (e.g. a DCS-version mismatch) the call raises listing the rejected assignments WITHOUT writing -- it never auto-forces. To write anyway, replay via set_payload(force=True). Returns: {unit_id, aircraft_type, applied_loadout, loadout_role, loadout_role_numeric, candidates_considered, pylons, coverage} Raises: ValueError unit_id unknown / not an aircraft, role unknown, or zero loadouts match the role (+ optional substring). RuntimeError DCS install path not configured. FileNotFoundError no UnitPayloads file exists for this aircraft type.

Reads <DCS Install>/CoreMods/.../UnitPayloads/<aircraft_type>.lua (stock) and the Saved Games MissionEditor/UnitPayloads file (user overrides, if present). User entries override stock entries that share a displayName; new user entries are appended. Returns: {aircraft_type, source_files: [...], role_filter: <name|null>, loadouts: [{displayName, name, role, role_numeric, task_ids, pylons}]} Raises: ValueError aircraft_type unknown, or role matches no task type. RuntimeError DCS install path not configured. FileNotFoundError no UnitPayloads file exists for this aircraft_type.

unit_type: DCS type string, e.g. 'FA-18C_hornet' -- use list_unit_types with category='plane' or 'helicopter' to find the right id. Returns {pylon_number: [{name, clsid, weight}, ...]} for each pylon that has at least one loadable weapon. The 'clsid' value is what set_payload currently expects. The 'name' field is the human-readable weapon label. Only applies to planes and helicopters -- vehicles/ships/statics have no pylon system.

Livery names are airframe-specific. Use list_liveries to enumerate. Pass an empty string to revert to the default livery.

unit_type: DCS type string -- use list_unit_types to find the right id. Returns [{name, id}] sorted by name. The 'id' field is what set_livery expects. Pass an empty string to set_livery to revert to the default livery. Only applies to planes and helicopters.

Reports which radios exist (by radio_id), how many channels each has, and what frequency is currently set on each channel. has_panel_radio: True if the airframe supports configurable preset channels. If False, radios is [] and a warning explains. is_client_or_player: True if presets will actually take effect in DCS. AI units' presets are persisted but ignored at runtime. Use this as the discovery call before set_radio_presets to confirm valid radio_ids and channel numbers for the airframe.

Returns 0 if the unit has no configurable radios or radio_id is invalid. Does NOT raise on these conditions (unlike the setter tools -- this is a query). For the full channel map use list_radios.

presets: dict mapping channel numbers to frequencies in MHz. Both string and integer keys are accepted (JSON sends strings). e.g. {"1": 251.0, "2": 252.0, "5": 254.5} Transactional: ALL channels and frequencies are validated before ANY are applied. If one channel is invalid, the call raises without mutating anything. An empty presets dict is a no-op (returns current state without mutation). previous_presets: snapshot of all channels on this radio before the call, so callers can see exactly what changed. NOTE: DCS will overwrite channel 1 of the intra-flight radio with the group's intra-flight frequency. Call set_intra_flight_frequency first.

radio_id: typically 1 or 2 on modern jets. Use list_radios to confirm valid radio_ids for the airframe. channel: the preset knob position (1-20 on F/A-18C, etc.). Use list_radios or num_radio_channels to see valid channels. frequency_mhz: must be > 0. previous_frequency_mhz: what was set before this call, for tracking. NOTE: DCS will overwrite channel 1 of the intra-flight radio with the group's intra-flight frequency. Call set_intra_flight_frequency first, then configure channels 2+ to avoid channel 1 being clobbered later. Warns (does not raise) if the unit is AI -- presets are persisted to the .miz but DCS does not apply them at runtime.

Convenience wrapper for the common "set the primary channel" pattern. Equivalent to set_radio_channel_preset(radio_id=1, channel=1, ...).

Reverts all preset channels to the values defined in the aircraft type's panel_radio defaults. Useful for undoing set_radio_presets changes. Raises if the airframe has no configurable radios (same behaviour as the setter tools).

Sets fg.frequency and -- for each Client/Player unit with configurable radios -- overwrites channel 1 of radio_id with this frequency. IMPORTANT -- Channel-1 clobber: DCS mandates that channel 1 of the intra-flight radio always equals the group frequency. This call WILL overwrite channel 1 on every qualifying unit in the group. Warnings are issued for each unit where ch 1 changes value. Recommended authoring order: 1. set_intra_flight_frequency (fixes ch 1 to the intra-flight freq) 2. set_radio_presets for channels 2+ (these are never clobbered) Waypoint SetFrequency tasks: macro-built tankers/AWACS (create_refuel_flight / create_awacs_flight) carry a SetFrequency WrappedAction on a route waypoint, and that task WINS over fg.frequency at runtime. This call also rewrites every SetFrequency task on the route to the new frequency, so the change actually takes effect; waypoint_tasks_updated reports how many were rewritten (0 for plain flights). Group-level triggered SetFrequency tasks (the rare add_triggered_action location, fg.tasks) are NOT touched. client_units_affected: how many Client/Player units had ch 1 updated. ai_units_in_group: informational; AI units' presets are not modified.

Kneeboard pages live in a raw KNEEBOARD/ ZIP folder -- they have NO resource key and are not referenced from the mission dict; DCS shows them in-cockpit by folder location. Returns: scope - "generic" or "per_airframe" zip_path - the in-.miz path the page is stored at filename - image filename aircraft_id - type id (per-airframe only, else None) needs_in_sim_confirmation - True for per-airframe: the folder name is the best offline answer (type id) but is only proven by the live jet rendering it

Kneeboard pages are stored at KNEEBOARD/<aircraft_id>/IMAGES/<filename> inside the .miz. They have NO resource key and cannot be referenced in trigger actions. They are visible in-cockpit to all pilots of that airframe type regardless of coalition or group. DCS does NOT support flight-specific kneeboards -- the page is shown to every pilot flying that type in the mission.

Surfaces pages from both storages: those added this session and those carried over from a loaded .miz. Each entry carries its in-zip `zip_path`, which is the handle remove_kneeboard takes. Returns: kneeboard_count - total pages generic - pages under KNEEBOARD/IMAGES/ (all airframes) per_airframe - pages under KNEEBOARD/<TYPE>/IMAGES/, with aircraft_id

Looks the page up in both storages (binary_files pass-through and the session aircraft_kneeboards) and drops it so it is no longer embedded on save. Kneeboards carry no resource key, so removing the entry leaves no orphan: after add-then-remove the ZIP tree returns to its prior state. zip_path: the exact path as reported by list_kneeboards / add_kneeboard_image (e.g. "KNEEBOARD/IMAGES/page.png" or "KNEEBOARD/A-10C_2/IMAGES/page.png"). Returns: zip_path - the removed path scope - "generic" or "per_airframe" source - which storage it was removed from ("loaded" / "session")

All three parameters are optional -- only the ones you supply are changed; the rest keep their existing value. description: general mission description shown to all players blue_task: briefing text for the blue (player) coalition red_task: briefing text for the red coalition Returns the resulting text for all three fields.

Clears the tab, garbage-collects any now-unreferenced previous images (orphan-free), then embeds and appends each filepath in order. Pass an empty list to clear the tab. Use this when you want to define a tab's pictures wholesale rather than add/remove one at a time. coalition: "blue", "red", "neutral", or "server". filepaths: list of absolute image paths (.png .jpg .jpeg .bmp), in the order they should appear. Each is magic-byte validated BEFORE any change is made (all-or-nothing). Returns: coalition - normalised tab name resource_keys - the ResKey_N strings now on this tab, in order previous_count - how many pictures the tab held before resources_deleted - previous keys that were garbage-collected

The image is embedded into the resource pool and appended to the specified tab's pictureFileName list. It appears in the DCS briefing screen for that tab. A tab can hold multiple images (call repeatedly). coalition: "blue", "red", "neutral", or "server" (the multiplayer-server briefing tab; "white" is accepted as an alias for "neutral"). filepath: absolute path to an image file (.png .jpg .jpeg .bmp). Validated by magic bytes. Must remain at this path until save_miz is called. Returns: resource_key - the ResKey_N string (also listed by list_resources) coalition - normalised tab name filename - image filename tab_count - number of pictures now on this tab

Drops the reference from the named tab's picture list, THEN deletes the underlying resource (mapResource entry + embedded file) only if no other tab or trigger still references it. If the same image is shared by another tab, the file is kept -- only this tab's reference is removed. This guarantees no orphaned resource is left behind. coalition: "blue", "red", "neutral", or "server". resource_key: the ResKey_N string (from add_briefing_picture or list_resources) to remove from this tab. Returns: coalition - normalised tab name resource_key - the key removed from the tab references_removed - how many entries were removed from this tab resource_deleted - True if the resource was garbage-collected remaining_referrers - where the resource is still referenced (if kept)

The returned resource_key (e.g. "ResKey_123") is what you pass to trigger actions such as RadioTransmission that reference a file by key. filepath: absolute path to a file on the local filesystem. Must remain at this path until save_miz is called. Supported extensions: images (.png .jpg .jpeg .bmp), sounds (.ogg .wav), scripts (.lua). Returns: resource_key - the ResKey_N string to use in trigger action params filepath - the absolute path as stored internally filename - just the filename portion resource_type - "image", "sound", or "script"

Returns four sections: resources - named resources with resource keys (usable in trigger actions); includes images, sounds, scripts. These are listed in mapResource and are the only ones remove_resource can target. briefing_pictures - per-tab lists of briefing picture keys, one list each for blue / red / neutral / server. Each key also appears in the resources list. kneeboards - per-airframe kneeboard pages added via add_aircraft_kneeboard in this session. These have NO resource key. Stored at KNEEBOARD/<aircraft_id>/IMAGES/ inside the .miz. NOTE: kneeboards from a loaded mission appear in binary_files, not in the kneeboards section. Only kneeboards added via add_aircraft_kneeboard in the current session appear in the kneeboards section.

Removes the resource from the pool (it stops being embedded on save) AND strips it from all four briefing tabs, so the inverse of an orphan -- a reference pointing at a deleted file -- can't be left behind either. To remove an image from only ONE briefing tab while keeping it on others, use remove_briefing_picture (reference-aware, GC-on-last-use) instead. Trigger actions that reference the key (e.g. a TransmitMessage sound) CANNOT be safely auto-edited, so they are reported as warnings for you to resolve -- the resource is still removed from the pool. resource_key: the ResKey_N string as returned by add_resource, add_briefing_picture, or list_resources. Returns: resource_key - the removed key filename - filename of the removed resource tabs_dereferenced - briefing tabs the key was removed from warnings - trigger references that may now be dangling

All parameters are optional -- omit to keep existing value. preset: named shorthand that sets multiple fields at once: "clear" -- clear sky, 15 km vis, calm wind "overcast" -- overcast, 5 km vis, moderate wind "fog" -- heavy fog, 800 m vis, calm "rain" -- rain, 3 km vis, moderate wind "thunderstorm" -- storm, 2 km vis, strong wind, turbulence Individual field overrides (applied after preset, if any): visibility_m -- horizontal visibility in metres (80-80000) wind_ground_speed_ms -- surface wind speed m/s wind_ground_dir -- surface wind from (degrees true, 0=N) wind_2000_speed_ms / wind_2000_dir -- wind at 2000 m wind_8000_speed_ms / wind_8000_dir -- wind at 8000 m temperature_c -- surface temperature in Celsius fog / fog_visibility_m -- enable fog and set its visibility dust / dust_density -- enable dust and set density (0-1000) Returns a summary of the resulting weather state.

All parameters are optional -- omitted ones keep their existing value. hour/minute/second: 24-hour UTC clock (e.g. hour=6 for 06:00Z dawn) year/month/day: calendar date (e.g. year=2025, month=3, day=21) Common usage: set_start_time(session_id, hour=6) -- change to 06:00 UTC same date set_start_time(session_id, hour=14, month=8) -- afternoon in August Returns the resulting start_time as an ISO 8601 string.

Combines heading_between + distance_between for the most common mission-authoring query: "what's the bearing and range from the airbase to the target?" heading_deg: 0=North, 90=East, 0-360. reciprocal_deg: pre-computed return bearing. Distance returned in meters, kilometers, and nautical miles. NOTE: Uses planar theater-XY geometry, not great-circle.

distance_nm is provided for aviation convenience (1 NM = 1852 m). distance_km = distance_m / 1000. NOTE: Uses planar theater-XY geometry, not great-circle. Error is sub-meter within a single DCS theater.