ZoneAttackAlert

Version: v3.4.0

A DCS World Lua mission script that sends coalition-specific attack alerts when ground or ship units inside defined trigger zones are hit.

Overview

ZoneAttackAlert monitors the DCS World event stream for S_EVENT_HIT events. When a ground unit or ship inside a configured trigger zone is hit, the script broadcasts a location-aware alert message to the coalition that owns the actual unit being hit (read dynamically via target:getCoalition()). Blue coalition receives distances in nautical miles (NM) and English alert text; Red coalition receives distances in kilometers (KM) and German alert text. A per-zone, per-coalition cooldown timer prevents message spam.

Features

• S_EVENT_HIT only — Listens exclusively for hit events; no kill or dead event handling
• No friendly-fire filter — Alerts trigger regardless of which coalition fired the shot
• Units only — Static objects (buildings, scenery, parked weapons) and structures never alert; only Unit.Category.GROUND_UNIT and Unit.Category.SHIP do
• Zone-based filtering — Only hits inside configured trigger zones produce alerts
• Per-zone, per-coalition cooldown — 180-second cooldown per (zone, coalition) pair; a Red hit in a shared zone never silences the Blue side
• Overlapping-zone safety — When zones overlap, one hit produces one alert and stamps the cooldown on every containing zone
• Hit-position callouts — Location strings are built from the actual hit position, not the zone centre
• Dynamic location callouts — Location strings built at alert-time relative to the nearest airbase, using the recipient's preferred units
• Coalition-specific language — English for Blue (ALERT: Friendly forces under attack!); German for Red (ALARM: Freundliche Kräfte unter Beschuss!)
• Coalition-specific units — NM for Blue, KM for Red
• Cardinal direction navigation — Location described as "north-east of Kobuleti" (Blue, in English) or "nordöstlich von Kobuleti" (Red, in German)
• Coalition-aware airbase reference — The callout prefers an airbase of the recipient's own coalition, so Red players are not directed to an Allied field
• Nearest airbase reference — All distances are relative to the closest airbase
• Reload-safe — Duplicate script loads are detected and skipped; a stale handler from a previous instance is removed on re-init
• Missing-zone warning — Trigger zones that do not exist in the mission are reported in DCS.log at startup
• Debug logging — Toggle config.debug to emit [ZAA] prefixed diagnostics to DCS.log

Logic Flow Diagrams

Initialization Flow

Event Handler Flow

Airbase Distance Lookup

Cooldown Logic

Message Construction Flow

Changes in v3.4

Correctness

Performance

The hit handler runs on every S_EVENT_HIT event in the mission, so the work is ordered cheapest-first:

Changes in v3.3

Robust Coalition Detection

Configuration

ZAA.config = {
    zone_names = {
        "RT1", "RT2", "RT3", "RT4", "RT5",
        "BT1", "BT2", "BT3", "BT4", "BT5"
    },
    message_cooldown = 180,   -- seconds per zone per coalition
    message_duration   = 18,  -- seconds on screen
    debug              = false, -- enable DCS.log diagnostics
    show_startup_message       = false, -- show "ZAA Running" to players
    prefer_own_coalition_airbase = true, -- reference an airbase of the recipient's side
}

Zone prefixes:

• RT* — Red Team trigger zones
• BT* — Blue Team trigger zones

Note: Prefixes are for organisational convenience only. Alert routing is determined by target:getCoalition() at runtime, so a Blue unit inside an RT* zone will alert Blue, and a Red unit inside a BT* zone will alert Red.

Debug Logging

Set debug = true in the config table to emit detailed diagnostics to the DCS log file. When enabled the script logs every step of event processing, including zone cache initialization, hit-event receipt, target validation, distance checks against each zone, cooldown state, the detected target coalition, and the final alert dispatch. When disabled, none of the diagnostic strings are built, so the hot path stays free of debug overhead.

Script Architecture

ZoneAttackAlert.lua
├── RELOAD GUARD (skip if ZAA.loaded already set; remove stale handler)
├── ZAA CONFIGURATION (table, user-editable)
├── GLOBAL LOCALIZATION (captured locals for hot path)
├── STATIC DATA (cardinal_directions)
├── ZONE CACHE (built at load time; geometry + bounding box, no coalition)
├── AIRBASE CACHE (built at load time; grouped by coalition)
├── build_zone_loc() (runtime location formatter, NM for Blue / KM for Red)
│   └── Compass bearing: atan2(East, North) using DCS axes (+x=N, +z=E)
├── STATE (last_alert_time table, keyed zone + coalition)
└── EVENT HANDLER (onEvent -> S_EVENT_HIT only, stored in ZAA.event_handler)

DCS Coordinate System Reference

ZoneAttackAlert uses the DCS world coordinate system for all bearing and distance calculations:

• +x = North
• +z = East
• +y = Up (altitude)

The compass bearing from North is computed with the standard formula:

local north_offset = px - airbase.x   -- positive when target is North
local east_offset  = pz - airbase.z   -- positive when target is East
local bearing_deg  = math.deg(math.atan2(east_offset, north_offset)) % 360

This follows the DCS scripting engine FAQ definition (atan2(East, North)) and requires no additional rotational offsets. The result is a clockwise bearing from North in the range [0, 360).

Testing

zaa_test.lua runs the real script against a mock DCS API (world, trigger, Unit, coalition, env, timer) and asserts its behaviour — no DCS installation required.

cd ZAA
lua zaa_test.lua

The script under test defaults to ZoneAttackAlert.lua next to the harness; point it elsewhere with the ZAA_SCRIPT environment variable:

ZAA_SCRIPT=/path/to/ZoneAttackAlert.lua lua zaa_test.lua

The harness covers the unit/static-object filter, the per-coalition cooldown, overlapping zones, hit-position callouts, coalition-aware airbase selection, hot-reload behaviour, and the defensive nil handling. It runs on Lua 5.1 (DCS) and 5.4.

Installation

1. Copy ZoneAttackAlert.lua to your DCS mission's trigger DO SCRIPT action or load it via require in your mission scripting
2. Ensure trigger zones named RT1–RT5 and BT1–BT5 exist in your mission
3. Run the mission; alerts appear automatically when criteria are met

Dependencies

• DCS World (any version supporting world.addEventHandler)
• No external libraries required (standalone)

Version History